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 file descriptor associated with it. pathname must point to a non-existing directory in the mount point of the SPU file system (SPUFS). If spu_create() is successful, a directory is created in pathname and it is populated with the files described in spufs(7).

The returned file descriptor can only be passed to spu_run(2) or closed; other operations are not defined on it. A logical SPU context is destroyed when its file descriptor is closed as well as all the file descriptors pointing to files inside it. When an SPU context is destroyed all its directory entries in the SPUFS are removed.

The argument flags can be zero or the following constant:

SPU_RAWIO

Allow mapping of some of the hardware registers of the SPU into user space. This flag requires the CAP_SYS_RAWIO capability.

The new directory and files are created in the SPUFS with the permissions set by the mode argument minus those set in the process's umask(2). The actual permissions set for each file also depend on whether the file supports read and/or write accesses.

RETURN VALUE

On success, spu_create(2) returns a new file descriptor. On error, −1 is returned and errno is set to one of the error codes listed below.

ERRORS

EACCES

The current user does not have write access to the SPUFS mount point.

EEXIST

An SPU context already exists in 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 files limit.

ENAMETOOLONG

pathname is too long.

ENFILE

The system has reached the global open files 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.

FILES

pathname must point to a location beneath the mount point of the SPUFS. By convention, it gets mounted in /spu.

VERSIONS

The spu_create(2) system call was added to Linux in kernel 2.6.16.

CONFORMING TO

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

NOTES

Glibc does not provide a wrapper for this system call; call it using syscall(2). Note however, that 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 recommended libraries.

BUGS

The code does not yet fully implement all features outlined here.

SEE ALSO

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


  This is _*_ nroff _*_ source. Emacs, gimme all those colors :)

Copyright (c) International Business Machines  Corp., 2006

This program is free software;  you can redistribute it and/or
modify it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 2 of
the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY;  without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See
the GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program;  if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston,
MA 02111-1307 USA

HISTORY:
2005-09-28, created by Arnd Bergmann <arndbde.ibm.com>
2006-06-16, revised by Eduardo M. Fleury <efleurybr.ibm.com>
2007-07-10, some polishing by mtk