{
    "mode": "man",
    "parameter": "spufs",
    "section": "7",
    "url": "https://www.chedong.com/phpMan.php/man/spufs/7/json",
    "generated": "2026-06-15T16:42:30Z",
    "sections": {
        "NAME": {
            "content": "spufs - SPU filesystem\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "The  SPU  filesystem is used on PowerPC machines that implement the Cell Broadband Engine Ar‐\nchitecture in order to access Synergistic Processor Units (SPUs).\n\nThe filesystem provides a name space similar to POSIX shared memory or message queues.  Users\nthat have write permissions on the filesystem can use spucreate(2) to establish SPU contexts\nunder the spufs root directory.\n\nEvery SPU context is represented by a directory containing a predefined set of files.   These\nfiles  can  be  used for manipulating the state of the logical SPU.  Users can change permis‐\nsions on the files, but can't add or remove files.\n",
            "subsections": [
                {
                    "name": "Mount options",
                    "content": ""
                },
                {
                    "name": "uid=<uid>",
                    "content": "Set the user owning the mount point; the default is 0 (root).\n"
                },
                {
                    "name": "gid=<gid>",
                    "content": "Set the group owning the mount point; the default is 0 (root).\n"
                },
                {
                    "name": "mode=<mode>",
                    "content": "Set the mode of the top-level directory in spufs, as an octal mode  string.   The  de‐\nfault is 0775.\n"
                },
                {
                    "name": "Files",
                    "content": "The  files in spufs mostly follow the standard behavior for regular system calls like read(2)\nor write(2), but often support only a subset of the operations supported on regular  filesys‐\ntems.  This list details the supported operations and the deviations from the standard behav‐\nior described in the respective man pages.\n\nAll files that support the read(2) operation also support readv(2) and all files that support\nthe  write(2)  operation also support writev(2).  All files support the access(2) and stat(2)\nfamily of operations, but for the latter call, the only fields of the returned stat structure\nthat contain reliable information are stmode, stnlink, stuid, and stgid.\n\nAll  files  support the chmod(2)/fchmod(2) and chown(2)/fchown(2) operations, but will not be\nable to grant permissions that contradict the possible operations (e.g., read access  on  the\nwbox file).\n\nThe current set of files is:\n\n/capabilities\nContains  a  comma-delimited string representing the capabilities of this SPU context.\nPossible capabilities are:\n\nsched  This context may be scheduled.\n\nstep   This context can be run in single-step mode, for debugging.\n\nNew capabilities flags may be added in the future.\n\n/mem   the contents of the local storage memory of the SPU.  This can be accessed like a reg‐\nular  shared  memory  file and contains both code and data in the address space of the\nSPU.  The possible operations on an open mem file are:\n\nread(2), pread(2), write(2), pwrite(2), lseek(2)\nThese operate as  usual,  with  the  exception  that  lseek(2),  write(2),  and\npwrite(2)  are  not supported beyond the end of the file.  The file size is the\nsize of the local storage of the SPU, which is normally 256 kilobytes.\n\nmmap(2)\nMapping mem into the process address space provides access  to  the  SPU  local\nstorage  within  the  process  address space.  Only MAPSHARED mappings are al‐\nlowed.\n\n/regs  Contains the saved general-purpose registers of the SPU context.  This  file  contains\nthe  128-bit values of each register, from register 0 to register 127, in order.  This\nallows the general-purpose registers to be inspected for debugging.\n\nReading to or writing from this file requires that the context is  scheduled  out,  so\nuse of this file is not recommended in normal program operation.\n\nThe  regs  file  is  not  present on contexts that have been created with the SPUCRE‐‐\nATENOSCHED flag.\n\n/mbox  The first SPU-to-CPU communication mailbox.  This file is read-only and can be read in\nunits of 4 bytes.  The file can be used only in nonblocking mode - even poll(2) cannot\nbe used to block on this file.  The only possible operation on an open mbox file is:\n\nread(2)\nIf count is smaller than four, read(2) returns -1 and sets errno to EINVAL.  If\nthere is no data available in the mailbox (i.e., the SPU has not sent a mailbox\nmessage), the return value is set to -1 and errno is set to EAGAIN.  When  data\nhas  been  read  successfully, four bytes are placed in the data buffer and the\nvalue four is returned.\n\n/ibox  The second SPU-to-CPU communication mailbox.  This file is similar to the first  mail‐\nbox  file,  but can be read in blocking I/O mode, thus calling read(2) on an open ibox\nfile will block until the SPU has written data to its interrupt mailbox  channel  (un‐\nless  the file has been opened with ONONBLOCK, see below).  Also, poll(2) and similar\nsystem calls can be used to monitor for the presence of mailbox data.\n\nThe possible operations on an open ibox file are:\n\nread(2)\nIf count is smaller than four, read(2) returns -1 and sets errno to EINVAL.  If\nthere  is  no  data  available  in the mailbox and the file descriptor has been\nopened with ONONBLOCK, the return value is set to -1 and errno is set  to  EA‐‐\nGAIN.\n\nIf  there  is no data available in the mailbox and the file descriptor has been\nopened without ONONBLOCK, the call will block until the SPU writes to its  in‐\nterrupt  mailbox channel.  When data has been read successfully, four bytes are\nplaced in the data buffer and the value four is returned.\n\npoll(2)\nPoll on the ibox file returns (POLLIN | POLLRDNORM) whenever data is  available\nfor reading.\n\n/wbox  The CPU-to-SPU communication mailbox.  It is write-only and can be written in units of\nfour bytes.  If the mailbox is full, write(2) will block, and poll(2) can be  used  to\nblock until the mailbox is available for writing again.  The possible operations on an\nopen wbox file are:\n\nwrite(2)\nIf count is smaller than four, write(2) returns -1 and sets  errno  to  EINVAL.\nIf  there is no space available in the mailbox and the file descriptor has been\nopened with ONONBLOCK, the return value is set to -1 and errno is set  to  EA‐‐\nGAIN.\n\nIf  there is no space available in the mailbox and the file descriptor has been\nopened without ONONBLOCK, the call will block until the SPU reads from its PPE\n(PowerPC  Processing Element) mailbox channel.  When data has been written suc‐\ncessfully, the system call returns four as its function result.\n\npoll(2)\nA poll on the wbox file returns (POLLOUT | POLLWRNORM) whenever space is avail‐\nable for writing.\n\n/mboxstat, /iboxstat, /wboxstat\nThese  are  read-only files that contain the length of the current queue of each mail‐\nbox—that is, how many words can be read from mbox or ibox or how  many  words  can  be\nwritten  to  wbox without blocking.  The files can be read only in four-byte units and\nreturn a big-endian binary integer number.  The only possible  operation  on  an  open\n*boxstat file is:\n\nread(2)\nIf  count  is  smaller  than four, read(2) returns -1 and sets errno to EINVAL.\nOtherwise, a four-byte value is placed in the data buffer.  This value  is  the\nnumber of elements that can be read from (for mboxstat and iboxstat) or writ‐\nten to (for wboxstat) the respective mailbox without blocking or returning  an\nEAGAIN error.\n\n/npc, /decr, /decrstatus, /sputagmask, /eventmask, /eventstatus, /srr0, /lslr\nInternal  registers  of the SPU.  These files contain an ASCII string representing the\nhex value of the specified register.  Reads and writes on these files (except for npc,\nsee  below) require that the SPU context be scheduled out, so frequent access to these\nfiles is not recommended for normal program operation.\n\nThe contents of these files are:\n\nnpc             Next Program Counter - valid only when the SPU is in a stopped state.\n\ndecr            SPU Decrementer\n\ndecrstatus     Decrementer Status\n\nsputagmask    MFC tag mask for SPU DMA\n\neventmask      Event mask for SPU interrupts\n\neventstatus    Number of SPU events pending (read-only)\n\nsrr0            Interrupt Return address register\n\nlslr            Local Store Limit Register\n\nThe possible operations on these files are:\n\nread(2)\nReads the current register value.  If the register value  is  larger  than  the\nbuffer  passed to the read(2) system call, subsequent reads will continue read‐\ning from the same buffer, until the end of the buffer is reached.\n\nWhen a complete string has been read, all subsequent read operations  will  re‐\nturn  zero  bytes  and  a  new file descriptor needs to be opened to read a new\nvalue.\n\nwrite(2)\nA write(2) operation on the file sets the register to the value  given  in  the\nstring.   The  string  is  parsed from the beginning until the first nonnumeric\ncharacter or the end of the buffer.  Subsequent writes to  the  same  file  de‐\nscriptor overwrite the previous setting.\n\nExcept for the npc file, these files are not present on contexts that have been\ncreated with the SPUCREATENOSCHED flag.\n\n/fpcr  This file provides access to the Floating Point Status and Control Register (fcpr)  as\na binary, four-byte file.  The operations on the fpcr file are:\n\nread(2)\nIf  count  is  smaller  than four, read(2) returns -1 and sets errno to EINVAL.\nOtherwise, a four-byte value is placed in the data buffer; this is the  current\nvalue of the fpcr register.\n\nwrite(2)\nIf  count  is  smaller than four, write(2) returns -1 and sets errno to EINVAL.\nOtherwise, a four-byte value is copied from the data buffer, updating the value\nof the fpcr register.\n\n/signal1, /signal2\nThe files provide access to the two signal notification channels of an SPU.  These are\nread-write files that operate on four-byte words.  Writing to one of these files trig‐\ngers  an interrupt on the SPU.  The value written to the signal files can be read from\nthe SPU through a channel read or from host user space through the  file.   After  the\nvalue  has  been  read by the SPU, it is reset to zero.  The possible operations on an\nopen signal1 or signal2 file are:\n\nread(2)\nIf count is smaller than four, read(2) returns -1 and  sets  errno  to  EINVAL.\nOtherwise,  a four-byte value is placed in the data buffer; this is the current\nvalue of the specified signal notification register.\n\nwrite(2)\nIf count is smaller than four, write(2) returns -1 and sets  errno  to  EINVAL.\nOtherwise, a four-byte value is copied from the data buffer, updating the value\nof the specified signal notification register.  The signal notification  regis‐\nter  will either be replaced with the input data or will be updated to the bit‐\nwise OR operation of the old value and the input data, depending  on  the  con‐\ntents of the signal1type or signal2type files respectively.\n\n/signal1type, /signal2type\nThese  two  files  change  the behavior of the signal1 and signal2 notification files.\nThey contain a numeric ASCII string which is read as either \"1\" or  \"0\".   In  mode  0\n(overwrite),  the  hardware  replaces the contents of the signal channel with the data\nthat is written to it.  In mode 1 (logical OR), the hardware accumulates the bits that\nare  subsequently  written  to it.  The possible operations on an open signal1type or\nsignal2type file are:\n\nread(2)\nWhen the count supplied to the read(2) call is shorter than the required length\nfor  the  digit (plus a newline character), subsequent reads from the same file\ndescriptor will complete the string.  When a complete string has been read, all\nsubsequent  read  operations  will  return zero bytes and a new file descriptor\nneeds to be opened to read the value again.\n\nwrite(2)\nA write(2) operation on the file sets the register to the value  given  in  the\nstring.   The  string  is  parsed from the beginning until the first nonnumeric\ncharacter or the end of the buffer.  Subsequent writes to  the  same  file  de‐\nscriptor overwrite the previous setting.\n\n/mboxinfo, /iboxinfo, /wboxinfo, /dmainto, /proxydmainfo\nRead-only  files  that  contain  the  saved state of the SPU mailboxes and DMA queues.\nThis allows the SPU status to be inspected, mainly for debugging.  The  mboxinfo  and\niboxinfo  files  each  contain the four-byte mailbox message that has been written by\nthe SPU.  If no message has been written to these mailboxes, then  contents  of  these\nfiles  is undefined.  The mboxstat, iboxstat, and wboxstat files contain the avail‐\nable message count.\n\nThe wboxinfo file contains an array of four-byte mailbox messages,  which  have  been\nsent to the SPU.  With current CBEA machines, the array is four items in length, so up\nto 4 * 4 = 16 bytes can be read from this file.  If any mailbox queue entry is  empty,\nthen the bytes read at the corresponding location are undefined.\n\nThe  dmainfo  file contains the contents of the SPU MFC DMA queue, represented as the\nfollowing structure:\n\nstruct spudmainfo {\nuint64t         dmainfotype;\nuint64t         dmainfomask;\nuint64t         dmainfostatus;\nuint64t         dmainfostallandnotify;\nuint64t         dmainfoatomiccommandstatus;\nstruct mfccqsr dmainfocommanddata[16];\n};\n\nThe last member of this data structure is the actual DMA queue, containing 16 entries.\nThe mfccqsr structure is defined as:\n\nstruct mfccqsr {\nuint64t mfccqdata0RW;\nuint64t mfccqdata1RW;\nuint64t mfccqdata2RW;\nuint64t mfccqdata3RW;\n};\n\nThe proxydmainfo file contains similar information, but describes the proxy DMA queue\n(i.e., DMAs initiated by entities outside the SPU) instead.  The file is in  the  fol‐\nlowing format:\n\nstruct spuproxydmainfo {\nuint64t         proxydmainfotype;\nuint64t         proxydmainfomask;\nuint64t         proxydmainfostatus;\nstruct mfccqsr proxydmainfocommanddata[8];\n};\n\nAccessing  these  files  requires that the SPU context is scheduled out - frequent use\ncan be inefficient.  These files should not be used for normal program operation.\n\nThese files are not present on contexts that  have  been  created  with  the  SPUCRE‐‐\nATENOSCHED flag.\n\n/cntl  This file provides access to the SPU Run Control and SPU status registers, as an ASCII\nstring.  The following operations are supported:\n\nread(2)\nReads from the cntl file will return an ASCII string with the hex value of  the\nSPU Status register.\n\nwrite(2)\nWrites to the cntl file will set the context's SPU Run Control register.\n\n/mfc   Provides  access  to the Memory Flow Controller of the SPU.  Reading from the file re‐\nturns the contents of the SPU's MFC Tag Status register, and writing to the file  ini‐\ntiates a DMA from the MFC.  The following operations are supported:\n\nwrite(2)\nWrites  to  this file need to be in the format of a MFC DMA command, defined as\nfollows:\n\nstruct mfcdmacommand {\nint32t  pad;    /* reserved */\nuint32t lsa;    /* local storage address */\nuint64t ea;     /* effective address */\nuint16t size;   /* transfer size */\nuint16t tag;    /* command tag */\nuint16t class;  /* class ID */\nuint16t cmd;    /* command opcode */\n};\n\nWrites are required to be exactly sizeof(struct mfcdmacommand) bytes in size.\nThe  command  will  be sent to the SPU's MFC proxy queue, and the tag stored in\nthe kernel (see below).\n\nread(2)\nReads the contents of the tag status register.  If the file is opened in block‐\ning  mode  (i.e., without ONONBLOCK), then the read will block until a DMA tag\n(as performed by a previous write) is complete.  In nonblocking mode,  the  MFC\ntag status register will be returned without waiting.\n\npoll(2)\nCalling  poll(2)  on the mfc file will block until a new DMA can be started (by\nchecking for POLLOUT) or until  a  previously  started  DMA  (by  checking  for\nPOLLIN) has been completed.\n\n/mss Provides access to the MFC MultiSource Synchronization (MSS) facility.  By\nmmap(2)-ing this file, processes can access the MSS area of the SPU.\n\nThe following operations are supported:\n\nmmap(2)\nMapping mss into the process address space gives access to  the  SPU  MSS  area\nwithin the process address space.  Only MAPSHARED mappings are allowed.\n\n/psmap Provides  access  to the whole problem-state mapping of the SPU.  Applications can use\nthis area to interface to the SPU, rather than writing to individual register files in\nspufs.\n\nThe following operations are supported:\n\nmmap(2)\nMapping psmap gives a process a direct map of the SPU problem state area.  Only\nMAPSHARED mappings are supported.\n\n/phys-id\nRead-only file containing the physical SPU number that the SPU context is running  on.\nWhen the context is not running, this file contains the string \"-1\".\n\nThe physical SPU number is given by an ASCII hex string.\n\n/object-id\nAllows  applications to store (or retrieve) a single 64-bit ID into the context.  This\nID is later used by profiling tools to uniquely identify the context.\n\nwrite(2)\nBy writing an ASCII hex value into this file, applications can set  the  object\nID of the SPU context.  Any previous value of the object ID is overwritten.\n\nread(2)\nReading this file gives an ASCII hex string representing the object ID for this\nSPU context.\n"
                }
            ]
        },
        "EXAMPLES": {
            "content": "/etc/fstab  entry\nnone      /spu      spufs     gid=spu   0    0\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "close(2), spucreate(2), spurun(2), capabilities(7)\n\nThe Cell Broadband Engine Architecture (CBEA) specification\n",
            "subsections": []
        },
        "COLOPHON": {
            "content": "This page is part of release 5.10 of the Linux  man-pages  project.   A  description  of  the\nproject,  information about reporting bugs, and the latest version of this page, can be found\nat https://www.kernel.org/doc/man-pages/.\n\n\n\nLinux                                        2020-12-21                                     SPUFS(7)",
            "subsections": []
        }
    },
    "summary": "spufs - SPU filesystem",
    "flags": [],
    "examples": [
        "/etc/fstab  entry",
        "none      /spu      spufs     gid=spu   0    0"
    ],
    "see_also": [
        {
            "name": "close",
            "section": "2",
            "url": "https://www.chedong.com/phpMan.php/man/close/2/json"
        },
        {
            "name": "spucreate",
            "section": "2",
            "url": "https://www.chedong.com/phpMan.php/man/spucreate/2/json"
        },
        {
            "name": "spurun",
            "section": "2",
            "url": "https://www.chedong.com/phpMan.php/man/spurun/2/json"
        },
        {
            "name": "capabilities",
            "section": "7",
            "url": "https://www.chedong.com/phpMan.php/man/capabilities/7/json"
        }
    ]
}