Documentation/filesystems/spufs/spufs.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 =====
   4 spufs
   5 =====
   6
   7 Name
   8 ====
   9
  10        spufs - the SPU file system
  11
  12
  13 Description
  14 ===========
  15
  16        The SPU file system is used on PowerPC machines that implement the Cell
  17        Broadband Engine Architecture in order to access Synergistic  Processor
  18        Units (SPUs).
  19
  20        The file system provides a name space similar to posix shared memory or
  21        message queues. Users that have write permissions on  the  file  system
  22        can use spu_create(2) to establish SPU contexts in the spufs root.
  23
  24        Every SPU context is represented by a directory containing a predefined
  25        set of files. These files can be used for manipulating the state of the
  26        logical SPU. Users can change permissions on those files, but not actu-
  27        ally add or remove files.
  28
  29
  30 Mount Options
  31 =============
  32
  33        uid=<uid>
  34               set the user owning the mount point, the default is 0 (root).
  35
  36        gid=<gid>
  37               set the group owning the mount point, the default is 0 (root).
  38
  39
  40 Files
  41 =====
  42
  43        The files in spufs mostly follow the standard behavior for regular sys-
  44        tem  calls like read(2) or write(2), but often support only a subset of
  45        the operations supported on regular file systems. This list details the
  46        supported  operations  and  the  deviations  from  the behaviour in the
  47        respective man pages.
  48
  49        All files that support the read(2) operation also support readv(2)  and
  50        all  files  that support the write(2) operation also support writev(2).
  51        All files support the access(2) and stat(2) family of  operations,  but
  52        only  the  st_mode,  st_nlink,  st_uid and st_gid fields of struct stat
  53        contain reliable information.
  54
  55        All files support the chmod(2)/fchmod(2) and chown(2)/fchown(2)  opera-
  56        tions,  but  will  not be able to grant permissions that contradict the
  57        possible operations, e.g. read access on the wbox file.
  58
  59        The current set of files is:
  60
  61
  62    /mem
  63        the contents of the local storage memory  of  the  SPU.   This  can  be
  64        accessed  like  a regular shared memory file and contains both code and
  65        data in the address space of the SPU.  The possible  operations  on  an
  66        open mem file are:
  67
  68        read(2), pread(2), write(2), pwrite(2), lseek(2)
  69               These  operate  as  documented, with the exception that seek(2),
  70               write(2) and pwrite(2) are not supported beyond the end  of  the
  71               file. The file size is the size of the local storage of the SPU,
  72               which normally is 256 kilobytes.
  73
  74        mmap(2)
  75               Mapping mem into the process address space gives access  to  the
  76               SPU  local  storage  within  the  process  address  space.  Only
  77               MAP_SHARED mappings are allowed.
  78
  79
  80    /mbox
  81        The first SPU to CPU communication mailbox. This file is read-only  and
  82        can  be  read  in  units of 32 bits.  The file can only be used in non-
  83        blocking mode and it even poll() will not block on  it.   The  possible
  84        operations on an open mbox file are:
  85
  86        read(2)
  87               If  a  count smaller than four is requested, read returns -1 and
  88               sets errno to EINVAL.  If there is no data available in the mail
  89               box,  the  return  value  is set to -1 and errno becomes EAGAIN.
  90               When data has been read successfully, four bytes are  placed  in
  91               the data buffer and the value four is returned.
  92
  93
  94    /ibox
  95        The  second  SPU  to CPU communication mailbox. This file is similar to
  96        the first mailbox file, but can be read in blocking I/O mode,  and  the
  97        poll  family of system calls can be used to wait for it.  The  possible
  98        operations on an open ibox file are:
  99
 100        read(2)
 101               If a count smaller than four is requested, read returns  -1  and
 102               sets errno to EINVAL.  If there is no data available in the mail
 103               box and the file descriptor has been opened with O_NONBLOCK, the
 104               return value is set to -1 and errno becomes EAGAIN.
 105
 106               If  there  is  no  data  available  in the mail box and the file
 107               descriptor has been opened without  O_NONBLOCK,  the  call  will
 108               block  until  the  SPU  writes to its interrupt mailbox channel.
 109               When data has been read successfully, four bytes are  placed  in
 110               the data buffer and the value four is returned.
 111
 112        poll(2)
 113               Poll  on  the  ibox  file returns (POLLIN | POLLRDNORM) whenever
 114               data is available for reading.
 115
 116
 117    /wbox
 118        The CPU to SPU communation mailbox. It is write-only and can be written
 119        in  units  of  32  bits. If the mailbox is full, write() will block and
 120        poll can be used to wait for it becoming  empty  again.   The  possible
 121        operations  on  an open wbox file are: write(2) If a count smaller than
 122        four is requested, write returns -1 and sets errno to EINVAL.  If there
 123        is  no space available in the mail box and the file descriptor has been
 124        opened with O_NONBLOCK, the return value is set to -1 and errno becomes
 125        EAGAIN.
 126
 127        If  there is no space available in the mail box and the file descriptor
 128        has been opened without O_NONBLOCK, the call will block until  the  SPU
 129        reads  from  its PPE mailbox channel.  When data has been read success-
 130        fully, four bytes are placed in the data buffer and the value  four  is
 131        returned.
 132
 133        poll(2)
 134               Poll  on  the  ibox file returns (POLLOUT | POLLWRNORM) whenever
 135               space is available for writing.
 136
 137
 138    /mbox_stat, /ibox_stat, /wbox_stat
 139        Read-only files that contain the length of the current queue, i.e.  how
 140        many  words  can  be  read  from  mbox or ibox or how many words can be
 141        written to wbox without blocking.  The files can be read only in 4-byte
 142        units  and  return  a  big-endian  binary integer number.  The possible
 143        operations on an open ``*box_stat`` file are:
 144
 145        read(2)
 146               If a count smaller than four is requested, read returns  -1  and
 147               sets errno to EINVAL.  Otherwise, a four byte value is placed in
 148               the data buffer, containing the number of elements that  can  be
 149               read  from  (for  mbox_stat  and  ibox_stat)  or written to (for
 150               wbox_stat) the respective mail box without blocking or resulting
 151               in EAGAIN.
 152
 153
 154    /npc, /decr, /decr_status, /spu_tag_mask, /event_mask, /srr0
 155        Internal  registers  of  the SPU. The representation is an ASCII string
 156        with the numeric value of the next instruction to  be  executed.  These
 157        can  be  used in read/write mode for debugging, but normal operation of
 158        programs should not rely on them because access to any of  them  except
 159        npc requires an SPU context save and is therefore very inefficient.
 160
 161        The contents of these files are:
 162
 163        =================== ===================================
 164        npc                 Next Program Counter
 165        decr                SPU Decrementer
 166        decr_status         Decrementer Status
 167        spu_tag_mask        MFC tag mask for SPU DMA
 168        event_mask          Event mask for SPU interrupts
 169        srr0                Interrupt Return address register
 170        =================== ===================================
 171
 172
 173        The   possible   operations   on   an   open  npc,  decr,  decr_status,
 174        spu_tag_mask, event_mask or srr0 file are:
 175
 176        read(2)
 177               When the count supplied to the read call  is  shorter  than  the
 178               required  length for the pointer value plus a newline character,
 179               subsequent reads from the same file descriptor  will  result  in
 180               completing  the string, regardless of changes to the register by
 181               a running SPU task.  When a complete string has been  read,  all
 182               subsequent read operations will return zero bytes and a new file
 183               descriptor needs to be opened to read the value again.
 184
 185        write(2)
 186               A write operation on the file results in setting the register to
 187               the  value  given  in  the string. The string is parsed from the
 188               beginning to the first non-numeric character or the end  of  the
 189               buffer.  Subsequent writes to the same file descriptor overwrite
 190               the previous setting.
 191
 192
 193    /fpcr
 194        This file gives access to the Floating Point Status and Control  Regis-
 195        ter as a four byte long file. The operations on the fpcr file are:
 196
 197        read(2)
 198               If  a  count smaller than four is requested, read returns -1 and
 199               sets errno to EINVAL.  Otherwise, a four byte value is placed in
 200               the data buffer, containing the current value of the fpcr regis-
 201               ter.
 202
 203        write(2)
 204               If a count smaller than four is requested, write returns -1  and
 205               sets  errno  to  EINVAL.  Otherwise, a four byte value is copied
 206               from the data buffer, updating the value of the fpcr register.
 207
 208
 209    /signal1, /signal2
 210        The two signal notification channels of an SPU.  These  are  read-write
 211        files  that  operate  on  a 32 bit word.  Writing to one of these files
 212        triggers an interrupt on the SPU.  The  value  written  to  the  signal
 213        files can be read from the SPU through a channel read or from host user
 214        space through the file.  After the value has been read by the  SPU,  it
 215        is  reset  to zero.  The possible operations on an open signal1 or sig-
 216        nal2 file are:
 217
 218        read(2)
 219               If a count smaller than four is requested, read returns  -1  and
 220               sets errno to EINVAL.  Otherwise, a four byte value is placed in
 221               the data buffer, containing the current value of  the  specified
 222               signal notification register.
 223
 224        write(2)
 225               If  a count smaller than four is requested, write returns -1 and
 226               sets errno to EINVAL.  Otherwise, a four byte  value  is  copied
 227               from the data buffer, updating the value of the specified signal
 228               notification register.  The signal  notification  register  will
 229               either be replaced with the input data or will be updated to the
 230               bitwise OR of the old value and the input data, depending on the
 231               contents  of  the  signal1_type,  or  signal2_type respectively,
 232               file.
 233
 234
 235    /signal1_type, /signal2_type
 236        These two files change the behavior of the signal1 and signal2  notifi-
 237        cation  files.  The  contain  a numerical ASCII string which is read as
 238        either "1" or "0".  In mode 0 (overwrite), the  hardware  replaces  the
 239        contents of the signal channel with the data that is written to it.  in
 240        mode 1 (logical OR), the hardware accumulates the bits that are  subse-
 241        quently written to it.  The possible operations on an open signal1_type
 242        or signal2_type file are:
 243
 244        read(2)
 245               When the count supplied to the read call  is  shorter  than  the
 246               required  length  for the digit plus a newline character, subse-
 247               quent reads from the same file descriptor will  result  in  com-
 248               pleting  the  string.  When a complete string has been read, all
 249               subsequent read operations will return zero bytes and a new file
 250               descriptor needs to be opened to read the value again.
 251
 252        write(2)
 253               A write operation on the file results in setting the register to
 254               the value given in the string. The string  is  parsed  from  the
 255               beginning  to  the first non-numeric character or the end of the
 256               buffer.  Subsequent writes to the same file descriptor overwrite
 257               the previous setting.
 258
 259
 260 Examples
 261 ========
 262        /etc/fstab entry
 263               none      /spu      spufs     gid=spu   0    0
 264
 265
 266 Authors
 267 =======
 268        Arnd  Bergmann  <arndb@de.ibm.com>,  Mark  Nutter <mnutter@us.ibm.com>,
 269        Ulrich Weigand <Ulrich.Weigand@de.ibm.com>
 270
 271 See Also
 272 ========
 273        capabilities(7), close(2), spu_create(2), spu_run(2), spufs(7)