spu_create() System Call in Linux

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 created 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 associated 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 ord combination of the following constants:

Tag	Description
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 users 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

Tag	Description
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 contexts 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.

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 architecture. 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>