summaryrefslogtreecommitdiffstats
path: root/Documentation/filesystems/spufs.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/filesystems/spufs.txt')
-rw-r--r--Documentation/filesystems/spufs.txt521
1 files changed, 0 insertions, 521 deletions
diff --git a/Documentation/filesystems/spufs.txt b/Documentation/filesystems/spufs.txt
deleted file mode 100644
index 1343d11..0000000
--- a/Documentation/filesystems/spufs.txt
+++ /dev/null
@@ -1,521 +0,0 @@
-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 actu-
- ally 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 sys-
- tem 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
- supported 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) opera-
- tions, but will not be able to grant permissions 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 family 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_NONBLOCK, 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 and 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_NONBLOCK, 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 success-
- fully, 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
- programs 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. Subsequent writes to the same file descriptor overwrite
- the previous setting.
-
-
- /fpcr
- This file gives access to the Floating Point Status and Control Regis-
- ter as a four byte long file. The operations 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 regis-
- ter.
-
- 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 written 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 sig-
- nal2 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 notification 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 register. 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 notifi-
- cation 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 subse-
- quently 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 newline character, subse-
- quent reads from the same file descriptor will result in com-
- pleting 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. Subsequent writes to the same file descriptor overwrite
- the previous setting.
-
-
-EXAMPLES
- /etc/fstab entry
- none /spu spufs gid=spu 0 0
-
-
-AUTHORS
- Arnd Bergmann <arndb@de.ibm.com>, Mark Nutter <mnutter@us.ibm.com>,
- Ulrich Weigand <Ulrich.Weigand@de.ibm.com>
-
-SEE ALSO
- capabilities(7), close(2), spu_create(2), spu_run(2), spufs(7)
-
-
-
-Linux 2005-09-28 SPUFS(2)
-
-------------------------------------------------------------------------------
-
-SPU_RUN(2) Linux Programmer's Manual SPU_RUN(2)
-
-
-
-NAME
- spu_run - execute an spu context
-
-
-SYNOPSIS
- #include <sys/spu.h>
-
- int spu_run(int fd, unsigned int *npc, unsigned int *event);
-
-DESCRIPTION
- The spu_run system call is used on PowerPC machines that implement the
- Cell Broadband Engine Architecture in order to access Synergistic Pro-
- cessor Units (SPUs). It uses the fd that was returned from spu_cre-
- ate(2) to address a specific SPU context. When the context gets sched-
- uled to a physical SPU, it starts execution at the instruction pointer
- passed in npc.
-
- Execution of SPU code happens synchronously, meaning that spu_run does
- not return while the SPU is still running. If there is a need to exe-
- cute SPU code in parallel with other code on either the main CPU or
- other SPUs, you need to create a new thread of execution first, e.g.
- using the pthread_create(3) call.
-
- When spu_run returns, the current value of the SPU instruction pointer
- is written back to npc, so you can call spu_run again without updating
- the pointers.
-
- event can be a NULL pointer or point to an extended status code that
- gets filled when spu_run returns. It can be one of the following con-
- stants:
-
- SPE_EVENT_DMA_ALIGNMENT
- A DMA alignment error
-
- SPE_EVENT_SPE_DATA_SEGMENT
- A DMA segmentation error
-
- SPE_EVENT_SPE_DATA_STORAGE
- A DMA storage error
-
- If NULL is passed as the event argument, these errors will result in a
- signal delivered to the calling process.
-
-RETURN VALUE
- spu_run returns the value of the spu_status register or -1 to indicate
- an error and set errno to one of the error codes listed below. The
- spu_status register value contains a bit mask of status codes and
- optionally a 14 bit code returned from the stop-and-signal instruction
- on the SPU. The bit masks for the status codes are:
-
- 0x02 SPU was stopped by stop-and-signal.
-
- 0x04 SPU was stopped by halt.
-
- 0x08 SPU is waiting for a channel.
-
- 0x10 SPU is in single-step mode.
-
- 0x20 SPU has tried to execute an invalid instruction.
-
- 0x40 SPU has tried to access an invalid channel.
-
- 0x3fff0000
- The bits masked with this value contain the code returned from
- stop-and-signal.
-
- There are always one or more of the lower eight bits set or an error
- code is returned from spu_run.
-
-ERRORS
- EAGAIN or EWOULDBLOCK
- fd is in non-blocking mode and spu_run would block.
-
- EBADF fd is not a valid file descriptor.
-
- EFAULT npc is not a valid pointer or status is neither NULL nor a valid
- pointer.
-
- EINTR A signal occurred while spu_run was in progress. The npc value
- has been updated to the new program counter value if necessary.
-
- EINVAL fd is not a file descriptor returned from spu_create(2).
-
- ENOMEM Insufficient memory was available to handle a page fault result-
- ing from an MFC direct memory access.
-
- ENOSYS the functionality is not provided by the current system, because
- either the hardware does not provide SPUs or the spufs module is
- not loaded.
-
-
-NOTES
- spu_run is meant to be used from libraries that implement a more
- abstract interface to SPUs, not to be used from regular applications.
- See http://www.bsc.es/projects/deepcomputing/linuxoncell/ for the rec-
- ommended libraries.
-
-
-CONFORMING TO
- This call is Linux specific and only implemented by the ppc64 architec-
- ture. Programs using this system call are not portable.
-
-
-BUGS
- The code does not yet fully implement all features lined out here.
-
-
-AUTHOR
- Arnd Bergmann <arndb@de.ibm.com>
-
-SEE ALSO
- capabilities(7), close(2), spu_create(2), spufs(7)
-
-
-
-Linux 2005-09-28 SPU_RUN(2)
-
-------------------------------------------------------------------------------
-
-SPU_CREATE(2) Linux Programmer's Manual SPU_CREATE(2)
-
-
-
-NAME
- spu_create - create a new spu context
-
-
-SYNOPSIS
- #include <sys/types.h>
- #include <sys/spu.h>
-
- int spu_create(const char *pathname, int flags, mode_t mode);
-
-DESCRIPTION
- The spu_create system call is used on PowerPC machines that implement
- the Cell Broadband Engine Architecture in order to access Synergistic
- Processor Units (SPUs). It creates a new logical context for an SPU in
- pathname and returns a handle to associated with it. pathname must
- point to a non-existing directory in the mount point of the SPU file
- system (spufs). When spu_create is successful, a directory gets cre-
- ated on pathname and it is populated with files.
-
- The returned file handle can only be passed to spu_run(2) or closed,
- other operations are not defined on it. When it is closed, all associ-
- ated directory entries in spufs are removed. When the last file handle
- pointing either inside of the context directory or to this file
- descriptor is closed, the logical SPU context is destroyed.
-
- The parameter flags can be zero or any bitwise or'd combination of the
- following constants:
-
- SPU_RAWIO
- Allow mapping of some of the hardware registers of the SPU into
- user space. This flag requires the CAP_SYS_RAWIO capability, see
- capabilities(7).
-
- The mode parameter specifies the permissions used for creating the new
- directory in spufs. mode is modified with the user's umask(2) value
- and then used for both the directory and the files contained in it. The
- file permissions mask out some more bits of mode because they typically
- support only read or write access. See stat(2) for a full list of the
- possible mode values.
-
-
-RETURN VALUE
- spu_create returns a new file descriptor. It may return -1 to indicate
- an error condition and set errno to one of the error codes listed
- below.
-
-
-ERRORS
- EACCESS
- The current user does not have write access on the spufs mount
- point.
-
- EEXIST An SPU context already exists at the given path name.
-
- EFAULT pathname is not a valid string pointer in the current address
- space.
-
- EINVAL pathname is not a directory in the spufs mount point.
-
- ELOOP Too many symlinks were found while resolving pathname.
-
- EMFILE The process has reached its maximum open file limit.
-
- ENAMETOOLONG
- pathname was too long.
-
- ENFILE The system has reached the global open file limit.
-
- ENOENT Part of pathname could not be resolved.
-
- ENOMEM The kernel could not allocate all resources required.
-
- ENOSPC There are not enough SPU resources available to create a new
- context or the user specific limit for the number of SPU con-
- texts has been reached.
-
- ENOSYS the functionality is not provided by the current system, because
- either the hardware does not provide SPUs or the spufs module is
- not loaded.
-
- ENOTDIR
- A part of pathname is not a directory.
-
-
-
-NOTES
- spu_create is meant to be used from libraries that implement a more
- abstract interface to SPUs, not to be used from regular applications.
- See http://www.bsc.es/projects/deepcomputing/linuxoncell/ for the rec-
- ommended libraries.
-
-
-FILES
- pathname must point to a location beneath the mount point of spufs. By
- convention, it gets mounted in /spu.
-
-
-CONFORMING TO
- This call is Linux specific and only implemented by the ppc64 architec-
- ture. Programs using this system call are not portable.
-
-
-BUGS
- The code does not yet fully implement all features lined out here.
-
-
-AUTHOR
- Arnd Bergmann <arndb@de.ibm.com>
-
-SEE ALSO
- capabilities(7), close(2), spu_run(2), spufs(7)
-
-
-
-Linux 2005-09-28 SPU_CREATE(2)