Documentation/filesystems/spufs/spu_create.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ==========
   4 spu_create
   5 ==========
   6
   7 Name
   8 ====
   9        spu_create - create a new spu context
  10
  11
  12 Synopsis
  13 ========
  14
  15        ::
  16
  17          #include <sys/types.h>
  18          #include <sys/spu.h>
  19
  20          int spu_create(const char *pathname, int flags, mode_t mode);
  21
  22 Description
  23 ===========
  24        The  spu_create  system call is used on PowerPC machines that implement
  25        the Cell Broadband Engine Architecture in order to  access  Synergistic
  26        Processor  Units (SPUs). It creates a new logical context for an SPU in
  27        pathname and returns a handle to associated  with  it.   pathname  must
  28        point  to  a  non-existing directory in the mount point of the SPU file
  29        system (spufs).  When spu_create is successful, a directory  gets  cre-
  30        ated on pathname and it is populated with files.
  31
  32        The  returned  file  handle can only be passed to spu_run(2) or closed,
  33        other operations are not defined on it. When it is closed, all  associ-
  34        ated  directory entries in spufs are removed. When the last file handle
  35        pointing either inside  of  the  context  directory  or  to  this  file
  36        descriptor is closed, the logical SPU context is destroyed.
  37
  38        The  parameter flags can be zero or any bitwise or'd combination of the
  39        following constants:
  40
  41        SPU_RAWIO
  42               Allow mapping of some of the hardware registers of the SPU  into
  43               user space. This flag requires the CAP_SYS_RAWIO capability, see
  44               capabilities(7).
  45
  46        The mode parameter specifies the permissions used for creating the  new
  47        directory  in  spufs.   mode is modified with the user's umask(2) value
  48        and then used for both the directory and the files contained in it. The
  49        file permissions mask out some more bits of mode because they typically
  50        support only read or write access. See stat(2) for a full list  of  the
  51        possible mode values.
  52
  53
  54 Return Value
  55 ============
  56        spu_create  returns a new file descriptor. It may return -1 to indicate
  57        an error condition and set errno to  one  of  the  error  codes  listed
  58        below.
  59
  60
  61 Errors
  62 ======
  63        EACCES
  64               The  current  user does not have write access on the spufs mount
  65               point.
  66
  67        EEXIST An SPU context already exists at the given path name.
  68
  69        EFAULT pathname is not a valid string pointer in  the  current  address
  70               space.
  71
  72        EINVAL pathname is not a directory in the spufs mount point.
  73
  74        ELOOP  Too many symlinks were found while resolving pathname.
  75
  76        EMFILE The process has reached its maximum open file limit.
  77
  78        ENAMETOOLONG
  79               pathname was too long.
  80
  81        ENFILE The system has reached the global open file limit.
  82
  83        ENOENT Part of pathname could not be resolved.
  84
  85        ENOMEM The kernel could not allocate all resources required.
  86
  87        ENOSPC There  are  not  enough  SPU resources available to create a new
  88               context or the user specific limit for the number  of  SPU  con-
  89               texts has been reached.
  90
  91        ENOSYS the functionality is not provided by the current system, because
  92               either the hardware does not provide SPUs or the spufs module is
  93               not loaded.
  94
  95        ENOTDIR
  96               A part of pathname is not a directory.
  97
  98
  99
 100 Notes
 101 =====
 102        spu_create  is  meant  to  be used from libraries that implement a more
 103        abstract interface to SPUs, not to be used from  regular  applications.
 104        See  http://www.bsc.es/projects/deepcomputing/linuxoncell/ for the rec-
 105        ommended libraries.
 106
 107
 108 Files
 109 =====
 110        pathname must point to a location beneath the mount point of spufs.  By
 111        convention, it gets mounted in /spu.
 112
 113
 114 Conforming to
 115 =============
 116        This call is Linux specific and only implemented by the ppc64 architec-
 117        ture. Programs using this system call are not portable.
 118
 119
 120 Bugs
 121 ====
 122        The code does not yet fully implement all features lined out here.
 123
 124
 125 Author
 126 ======
 127        Arnd Bergmann <arndb@de.ibm.com>
 128
 129 See Also
 130 ========
 131        capabilities(7), close(2), spu_run(2), spufs(7)