man2/spu_create.2

   1 .\" Copyright (c) International Business Machines Corp., 2006
   2 .\"
   3 .\" SPDX-License-Identifier: GPL-2.0-or-later
   4 .\"
   5 .\" HISTORY:
   6 .\" 2005-09-28, created by Arnd Bergmann <arndb@de.ibm.com>
   7 .\" 2006-06-16, revised by Eduardo M. Fleury <efleury@br.ibm.com>
   8 .\" 2007-07-10, some polishing by mtk
   9 .\" 2007-09-28, updates for newer kernels by Jeremy Kerr <jk@ozlabs.org>
  10 .\"
  11 .TH SPU_CREATE 2 2021-03-22 Linux "Linux Programmer's Manual"
  12 .SH NAME
  13 spu_create \- create a new spu context
  14 .SH LIBRARY
  15 Standard C library
  16 .RI ( libc ", " \-lc )
  17 .SH SYNOPSIS
  18 .nf
  19 .BR "#include <sys/spu.h>" "          /* Definition of " SPU_* " constants */"
  20 .BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
  21 .B #include <unistd.h>
  22 .PP
  23 .BI "int syscall(SYS_spu_create, const char *" pathname \
  24 ", unsigned int " flags ,
  25 .BI "            mode_t " mode ", int " neighbor_fd );
  26 .fi
  27 .PP
  28 .IR Note :
  29 glibc provides no wrapper for
  30 .BR spu_create (),
  31 necessitating the use of
  32 .BR syscall (2).
  33 .SH DESCRIPTION
  34 The
  35 .BR spu_create ()
  36 system call is used on PowerPC machines that implement the
  37 Cell Broadband Engine Architecture in order to access Synergistic
  38 Processor Units (SPUs).
  39 It creates a new logical context for an SPU in
  40 .I pathname
  41 and returns a file descriptor associated with it.
  42 .I pathname
  43 must refer to a nonexistent directory in the mount point of
  44 the SPU filesystem
  45 .RB ( spufs ).
  46 If
  47 .BR spu_create ()
  48 is successful, a directory is created at
  49 .I pathname
  50 and it is populated with the files described in
  51 .BR spufs (7).
  52 .PP
  53 When a context is created,
  54 the returned file descriptor can only be passed to
  55 .BR spu_run (2),
  56 used as the
  57 .I dirfd
  58 argument to the
  59 .B *at
  60 family of system calls (e.g.,
  61 .BR openat (2)),
  62 or closed;
  63 other operations are not defined.
  64 A logical SPU
  65 context is destroyed (along with all files created within the context's
  66 .I pathname
  67 directory) once the last reference to the context has gone;
  68 this usually occurs when the file descriptor returned by
  69 .BR spu_create ()
  70 is closed.
  71 .PP
  72 The
  73 .I mode
  74 argument (minus any bits set in the process's
  75 .BR umask (2))
  76 specifies the permissions used for creating the new directory in
  77 .BR spufs .
  78 See
  79 .BR stat (2)
  80 for a full list of the possible
  81 .I mode
  82 values.
  83 .PP
  84 The
  85 .I neighbor_fd
  86 is used only when the
  87 .B SPU_CREATE_AFFINITY_SPU
  88 flag is specified; see below.
  89 .PP
  90 The
  91 .I flags
  92 argument can be zero or any bitwise OR-ed
  93 combination of the following constants:
  94 .TP
  95 .B SPU_CREATE_EVENTS_ENABLED
  96 Rather than using signals for reporting DMA errors, use the
  97 .I event
  98 argument to
  99 .BR spu_run (2).
 100 .TP
 101 .B SPU_CREATE_GANG
 102 Create an SPU gang instead of a context.
 103 (A gang is a group of SPU contexts that are
 104 functionally related to each other and which share common scheduling
 105 parameters\(empriority and policy.
 106 In the future, gang scheduling may be implemented causing
 107 the group to be switched in and out as a single unit.)
 108 .IP
 109 A new directory will be created at the location specified by the
 110 .I pathname
 111 argument.
 112 This gang may be used to hold other SPU contexts, by providing
 113 a pathname that is within the gang directory to further calls to
 114 .BR spu_create ().
 115 .TP
 116 .B SPU_CREATE_NOSCHED
 117 Create a context that is not affected by the SPU scheduler.
 118 Once the context is run,
 119 it will not be scheduled out until it is destroyed by
 120 the creating process.
 121 .IP
 122 Because the context cannot be removed from the SPU, some functionality
 123 is disabled for
 124 .B SPU_CREATE_NOSCHED
 125 contexts.
 126 Only a subset of the files will be
 127 available in this context directory in
 128 .BR spufs .
 129 Additionally,
 130 .B SPU_CREATE_NOSCHED
 131 contexts cannot dump a core file when crashing.
 132 .IP
 133 Creating
 134 .B SPU_CREATE_NOSCHED
 135 contexts requires the
 136 .B CAP_SYS_NICE
 137 capability.
 138 .TP
 139 .B SPU_CREATE_ISOLATE
 140 Create an isolated SPU context.
 141 Isolated contexts are protected from some
 142 PPE (PowerPC Processing Element)
 143 operations,
 144 such as access to the SPU local store and the NPC register.
 145 .IP
 146 Creating
 147 .B SPU_CREATE_ISOLATE
 148 contexts also requires the
 149 .B SPU_CREATE_NOSCHED
 150 flag.
 151 .TP
 152 .BR SPU_CREATE_AFFINITY_SPU " (since Linux 2.6.23)"
 153 .\" commit 8e68e2f248332a9c3fd4f08258f488c209bd3e0c
 154 Create a context with affinity to another SPU context.
 155 This affinity information is used within the SPU scheduling algorithm.
 156 Using this flag requires that a file descriptor referring to
 157 the other SPU context be passed in the
 158 .I neighbor_fd
 159 argument.
 160 .TP
 161 .BR SPU_CREATE_AFFINITY_MEM " (since Linux 2.6.23)"
 162 .\" commit 8e68e2f248332a9c3fd4f08258f488c209bd3e0c
 163 Create a context with affinity to system memory.
 164 This affinity information
 165 is used within the SPU scheduling algorithm.
 166 .SH RETURN VALUE
 167 On success,
 168 .BR spu_create ()
 169 returns a new file descriptor.
 170 On failure, \-1 is returned, and
 171 .I errno
 172 is set to indicate the error.
 173 .SH ERRORS
 174 .TP
 175 .B EACCES
 176 The current user does not have write access to the
 177 .BR spufs (7)
 178 mount point.
 179 .TP
 180 .B EEXIST
 181 An SPU context already exists at the given pathname.
 182 .TP
 183 .B EFAULT
 184 .I pathname
 185 is not a valid string pointer in the
 186 calling process's address space.
 187 .TP
 188 .B EINVAL
 189 .I pathname
 190 is not a directory in the
 191 .BR spufs (7)
 192 mount point, or invalid flags have been provided.
 193 .TP
 194 .B ELOOP
 195 Too many symbolic links were found while resolving
 196 .IR pathname .
 197 .TP
 198 .B EMFILE
 199 The per-process limit on the number of open file descriptors has been reached.
 200 .TP
 201 .B ENAMETOOLONG
 202 .I pathname
 203 is too long.
 204 .TP
 205 .B ENFILE
 206 The system-wide limit on the total number of open files has been reached.
 207 .TP
 208 .B ENODEV
 209 An isolated context was requested, but the hardware does not support
 210 SPU isolation.
 211 .TP
 212 .B ENOENT
 213 Part of
 214 .I pathname
 215 could not be resolved.
 216 .TP
 217 .B ENOMEM
 218 The kernel could not allocate all resources required.
 219 .TP
 220 .B ENOSPC
 221 There are not enough SPU resources available to create
 222 a new context or the user-specific limit for the number
 223 of SPU contexts has been reached.
 224 .TP
 225 .B ENOSYS
 226 The functionality is not provided by the current system, because
 227 either the hardware does not provide SPUs or the spufs module is not
 228 loaded.
 229 .TP
 230 .B ENOTDIR
 231 A part of
 232 .I pathname
 233 is not a directory.
 234 .TP
 235 .B EPERM
 236 The
 237 .B SPU_CREATE_NOSCHED
 238 flag has been given, but the user does not have the
 239 .B CAP_SYS_NICE
 240 capability.
 241 .SH FILES
 242 .I pathname
 243 must point to a location beneath the mount point of
 244 .BR spufs .
 245 By convention, it gets mounted in
 246 .IR /spu .
 247 .SH VERSIONS
 248 The
 249 .BR spu_create ()
 250 system call was added to Linux in kernel 2.6.16.
 251 .SH CONFORMING TO
 252 This call is Linux-specific and implemented only on the PowerPC
 253 architecture.
 254 Programs using this system call are not portable.
 255 .SH NOTES
 256 .BR spu_create ()
 257 is meant to be used from libraries that implement a more abstract
 258 interface to SPUs, not to be used from regular applications.
 259 See
 260 .UR http://www.bsc.es\:/projects\:/deepcomputing\:/linuxoncell/
 261 .UE
 262 for the recommended libraries.
 263 .PP
 264 Prior to the addition of the
 265 .B SPU_CREATE_AFFINITY_SPU
 266 flag in Linux 2.6.23, the
 267 .BR spu_create ()
 268 system call took only three arguments (i.e., there was no
 269 .I neighbor_fd
 270 argument).
 271 .SH EXAMPLES
 272 See
 273 .BR spu_run (2)
 274 for an example of the use of
 275 .BR spu_create ()
 276 .SH SEE ALSO
 277 .BR close (2),
 278 .BR spu_run (2),
 279 .BR capabilities (7),
 280 .BR spufs (7)