man2/spu_run.2

   1 .\" Copyright (c) International Business Machines Corp., 2006
   2 .\"
   3 .\" %%%LICENSE_START(GPLv2+_SW_3_PARA)
   4 .\" This program is free software; you can redistribute it and/or
   5 .\" modify it under the terms of the GNU General Public License as
   6 .\" published by the Free Software Foundation; either version 2 of
   7 .\" the License, or (at your option) any later version.
   8 .\"
   9 .\" This program is distributed in the hope that it will be useful,
  10 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
  12 .\" the GNU General Public License for more details.
  13 .\"
  14 .\" You should have received a copy of the GNU General Public
  15 .\" License along with this manual; if not, see
  16 .\" <http://www.gnu.org/licenses/>.
  17 .\" %%%LICENSE_END
  18 .\"
  19 .\" HISTORY:
  20 .\" 2005-09-28, created by Arnd Bergmann <arndb@de.ibm.com>
  21 .\" 2006-06-16, revised by Eduardo M. Fleury <efleury@br.ibm.com>
  22 .\" 2007-07-10, some polishing by mtk
  23 .\" 2007-09-28, updates for newer kernels, added example
  24 .\"             by Jeremy Kerr <jk@ozlabs.org>
  25 .\"
  26 .TH SPU_RUN 2 2021-03-22 Linux "Linux Programmer's Manual"
  27 .SH NAME
  28 spu_run \- execute an SPU context
  29 .SH SYNOPSIS
  30 .nf
  31 .BR "#include <sys/spu.h>" "          /* Definition of " SPU_* " constants */"
  32 .BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
  33 .B #include <unistd.h>
  34 .PP
  35 .BI "int spu_run(int " fd ", uint32_t *" npc ", uint32_t *" event );
  36 .fi
  37 .PP
  38 .IR Note :
  39 glibc provides no wrapper for
  40 .BR spu_run (),
  41 necessitating the use of
  42 .BR syscall (2).
  43 .SH DESCRIPTION
  44 The
  45 .BR spu_run ()
  46 system call is used on PowerPC machines that implement the
  47 Cell Broadband Engine Architecture in order to access Synergistic
  48 Processor Units (SPUs).
  49 The
  50 .I fd
  51 argument is a file descriptor returned by
  52 .BR spu_create (2)
  53 that refers to a specific SPU context.
  54 When the context gets scheduled to a physical SPU,
  55 it starts execution at the instruction pointer passed in
  56 .IR npc .
  57 .PP
  58 Execution of SPU code happens synchronously, meaning that
  59 .BR spu_run ()
  60 blocks while the SPU is still running.
  61 If there is a need
  62 to execute SPU code in parallel with other code on either the
  63 main CPU or other SPUs, a new thread of execution must be created
  64 first (e.g., using
  65 .BR pthread_create (3)).
  66 .PP
  67 When
  68 .BR spu_run ()
  69 returns, the current value of the SPU program counter is written to
  70 .IR npc ,
  71 so successive calls to
  72 .BR spu_run ()
  73 can use the same
  74 .I npc
  75 pointer.
  76 .PP
  77 The
  78 .I event
  79 argument provides a buffer for an extended status code.
  80 If the SPU
  81 context was created with the
  82 .B SPU_CREATE_EVENTS_ENABLED
  83 flag, then this buffer is populated by the Linux kernel before
  84 .BR spu_run ()
  85 returns.
  86 .PP
  87 The status code may be one (or more) of the following constants:
  88 .TP
  89 .B SPE_EVENT_DMA_ALIGNMENT
  90 A DMA alignment error occurred.
  91 .TP
  92 .B SPE_EVENT_INVALID_DMA
  93 An invalid MFC DMA command was attempted.
  94 .\" SPE_EVENT_SPE_DATA_SEGMENT is defined, but does not seem to be generated
  95 .\" at any point (in Linux 5.9 sources).
  96 .TP
  97 .B SPE_EVENT_SPE_DATA_STORAGE
  98 A DMA storage error occurred.
  99 .TP
 100 .B SPE_EVENT_SPE_ERROR
 101 An illegal instruction was executed.
 102 .PP
 103 NULL
 104 is a valid value for the
 105 .I event
 106 argument.
 107 In this case, the events will not be reported to the calling process.
 108 .SH RETURN VALUE
 109 On success,
 110 .BR spu_run ()
 111 returns the value of the
 112 .I spu_status
 113 register.
 114 On failure, it returns \-1 and sets
 115 .I errno
 116 is set to indicate the error.
 117 .PP
 118 The
 119 .I spu_status
 120 register value is a bit mask of status codes and
 121 optionally a 14-bit code returned from the
 122 .BR stop-and-signal
 123 instruction on the SPU.
 124 The bit masks for the status codes
 125 are:
 126 .TP
 127 .B 0x02
 128 SPU was stopped by a
 129 .BR stop-and-signal
 130 instruction.
 131 .TP
 132 .B 0x04
 133 SPU was stopped by a
 134 .BR halt
 135 instruction.
 136 .TP
 137 .B 0x08
 138 SPU is waiting for a channel.
 139 .TP
 140 .B 0x10
 141 SPU is in single-step mode.
 142 .TP
 143 .B 0x20
 144 SPU has tried to execute an invalid instruction.
 145 .TP
 146 .B 0x40
 147 SPU has tried to access an invalid channel.
 148 .TP
 149 .B 0x3fff0000
 150 The bits masked with this value contain the code returned from a
 151 .BR stop-and-signal
 152 instruction.
 153 These bits are valid only if the 0x02 bit is set.
 154 .PP
 155 If
 156 .BR spu_run ()
 157 has not returned an error, one or more bits among the lower eight
 158 ones are always set.
 159 .SH ERRORS
 160 .TP
 161 .B EBADF
 162 .I fd
 163 is not a valid file descriptor.
 164 .TP
 165 .B EFAULT
 166 .I npc
 167 is not a valid pointer, or
 168 .I event
 169 is non-NULL and an invalid pointer.
 170 .TP
 171 .B EINTR
 172 A signal occurred while
 173 .BR spu_run ()
 174 was in progress; see
 175 .BR signal (7).
 176 The
 177 .I npc
 178 value has been updated to the new program counter value if
 179 necessary.
 180 .TP
 181 .B EINVAL
 182 .I fd
 183 is not a valid file descriptor returned from
 184 .BR spu_create (2).
 185 .TP
 186 .B ENOMEM
 187 There was not enough memory available to handle a page fault
 188 resulting from a Memory Flow Controller (MFC) direct memory access.
 189 .TP
 190 .B ENOSYS
 191 The functionality is not provided by the current system, because
 192 either the hardware does not provide SPUs or the spufs module is not
 193 loaded.
 194 .SH VERSIONS
 195 The
 196 .BR spu_run ()
 197 system call was added to Linux in kernel 2.6.16.
 198 .SH CONFORMING TO
 199 This call is Linux-specific and implemented only by the PowerPC
 200 architecture.
 201 Programs using this system call are not portable.
 202 .SH NOTES
 203 .BR spu_run ()
 204 is meant to be used from libraries that implement a more abstract
 205 interface to SPUs, not to be used from regular applications.
 206 See
 207 .UR http://www.bsc.es\:/projects\:/deepcomputing\:/linuxoncell/
 208 .UE
 209 for the recommended libraries.
 210 .SH EXAMPLES
 211 The following is an example of running a simple, one-instruction SPU
 212 program with the
 213 .BR spu_run ()
 214 system call.
 215 .PP
 216 .EX
 217 #include <stdlib.h>
 218 #include <stdint.h>
 219 #include <unistd.h>
 220 #include <stdio.h>
 221 #include <sys/types.h>
 222 #include <fcntl.h>
 223
 224 #define handle_error(msg) \e
 225     do { perror(msg); exit(EXIT_FAILURE); } while (0)
 226
 227 int main(void)
 228 {
 229     int context, fd, spu_status;
 230     uint32_t instruction, npc;
 231
 232     context = spu_create("/spu/example\-context", 0, 0755);
 233     if (context == \-1)
 234         handle_error("spu_create");
 235
 236     /*
 237      * Write a \(aqstop 0x1234\(aq instruction to the SPU\(aqs
 238      * local store memory.
 239      */
 240     instruction = 0x00001234;
 241
 242     fd = open("/spu/example\-context/mem", O_RDWR);
 243     if (fd == \-1)
 244         handle_error("open");
 245     write(fd, &instruction, sizeof(instruction));
 246
 247     /*
 248      * set npc to the starting instruction address of the
 249      * SPU program. Since we wrote the instruction at the
 250      * start of the mem file, the entry point will be 0x0.
 251      */
 252     npc = 0;
 253
 254     spu_status = spu_run(context, &npc, NULL);
 255     if (spu_status == \-1)
 256         handle_error("open");
 257
 258     /*
 259      * We should see a status code of 0x1234002:
 260      *   0x00000002 (spu was stopped due to stop\-and\-signal)
 261      * | 0x12340000 (the stop\-and\-signal code)
 262      */
 263     printf("SPU Status: %#08x\en", spu_status);
 264
 265     exit(EXIT_SUCCESS);
 266 }
 267 .EE
 268 .\" .SH AUTHORS
 269 .\" Arnd Bergmann <arndb@de.ibm.com>, Jeremy Kerr <jk@ozlabs.org>
 270 .SH SEE ALSO
 271 .BR close (2),
 272 .BR spu_create (2),
 273 .BR capabilities (7),
 274 .BR spufs (7)