spu_create - create a new spu context

The spu_create system call is used on PowerPC machines that implementthe Cell Broadband Engine Architecture in order to access SynergisticProcessor Units (SPUs). It creates a new logical context for an SPU inpathname and returns a handle to associated with it. pathname mustpoint to a non-existing directory in the mount point of the SPU filesystem (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 handlepointing either inside of the context directory or to this filedescriptor is closed, the logical SPU context is destroyed.

The parameter flags can be zero or any bitwise or’d combination of thefollowing constants:

SPU_RAWIO

Allow mapping of some of the hardware registers of the SPU intouser space. This flag requires the CAP_SYS_RAWIO capability, seecapabilities(7).

The mode parameter specifies the permissions used for creating the newdirectory in spufs. mode is modified with the user’s umask(2) valueand then used for both the directory and the files contained in it. Thefile permissions mask out some more bits of mode because they typicallysupport only read or write access. See stat(2) for a full list of thepossible mode values.

spu_create returns a new file descriptor. It may return -1 to indicatean error condition and set errno to one of the error codes listedbelow.

EACCES

The current user does not have write access on the spufs mountpoint.

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 isnot loaded.

ENOTDIR

A part of pathname is not a directory.

spu_create is meant to be used from libraries that implement a moreabstract interface to SPUs, not to be used from regular applications.Seehttp://www.bsc.es/projects/deepcomputing/linuxoncell/ for the rec-ommended libraries.

pathname must point to a location beneath the mount point of spufs. Byconvention, it gets mounted in /spu.

This call is Linux specific and only implemented by the ppc64 architec-ture. Programs using this system call are not portable.

The code does not yet fully implement all features lined out here.

Arnd Bergmann <arndb@de.ibm.com>

capabilities(7), close(2), spu_run(2), spufs(7)