Man Pages

spufs(2) - phpMan spufs(2) - phpMan

Command: man perldoc info search(apropos)  


SPUFS(2)                   Linux Programmer's Manual                  SPUFS(2)



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  actually
       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 system 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  sup-
       ported 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) operations, but will not be able to grant per-
       missions 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 familiy 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_NON-
              BLOCK, 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 can 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_NON-
       BLOCK, 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  successfully,  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 pro-
       grams 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.  Subse-
              quent writes to the same file descriptor overwrite the previous setting.


   /fpcr
       This  file  gives access to the Floating Point Status and Control Register as a four byte long file. The opera-
       tions 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 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 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 writting 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 signal2 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  notifica-
              tion 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  reg-
              ister.   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 notification 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 subsequently 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 new-
              line character, subsequent reads from the same file descriptor will result  in  completing  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.  Subse-
              quent writes to the same file descriptor overwrite the previous setting.


EXAMPLES
       /etc/fstab entry
              none      /spu      spufs     gid=spu   0    0


AUTHORS
       Arnd Bergmann <arndbATde.com>, Mark Nutter <mnutterATus.com>, Ulrich Weigand <Ulrich.WeigandATde.com>

SEE ALSO
       capabilities(7), close(2), spu_create(2), spu_run(2), spufs(7)



Linux                             2005-09-28                          SPUFS(2)