man2/spu_run.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, added example
  10 .\"             by Jeremy Kerr <jk@ozlabs.org>
  11 .\"
  12 .TH spu_run 2 (date) "Linux man-pages (unreleased)"
  13 .SH NAME
  14 spu_run \- execute an SPU context
  15 .SH LIBRARY
  16 Standard C library
  17 .RI ( libc ", " \-lc )
  18 .SH SYNOPSIS
  19 .nf
  20 .BR "#include <sys/spu.h>" "          /* Definition of " SPU_* " constants */"
  21 .BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
  22 .B #include <unistd.h>
  23 .P
  24 .BI "int syscall(SYS_spu_run, int " fd ", uint32_t *" npc \
  25 ", uint32_t *" event );
  26 .fi
  27 .P
  28 .IR Note :
  29 glibc provides no wrapper for
  30 .BR spu_run (),
  31 necessitating the use of
  32 .BR syscall (2).
  33 .SH DESCRIPTION
  34 The
  35 .BR spu_run ()
  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 The
  40 .I fd
  41 argument is a file descriptor returned by
  42 .BR spu_create (2)
  43 that refers to a specific SPU context.
  44 When the context gets scheduled to a physical SPU,
  45 it starts execution at the instruction pointer passed in
  46 .IR npc .
  47 .P
  48 Execution of SPU code happens synchronously, meaning that
  49 .BR spu_run ()
  50 blocks while the SPU is still running.
  51 If there is a need
  52 to execute SPU code in parallel with other code on either the
  53 main CPU or other SPUs, a new thread of execution must be created
  54 first (e.g., using
  55 .BR pthread_create (3)).
  56 .P
  57 When
  58 .BR spu_run ()
  59 returns, the current value of the SPU program counter is written to
  60 .IR npc ,
  61 so successive calls to
  62 .BR spu_run ()
  63 can use the same
  64 .I npc
  65 pointer.
  66 .P
  67 The
  68 .I event
  69 argument provides a buffer for an extended status code.
  70 If the SPU
  71 context was created with the
  72 .B SPU_CREATE_EVENTS_ENABLED
  73 flag, then this buffer is populated by the Linux kernel before
  74 .BR spu_run ()
  75 returns.
  76 .P
  77 The status code may be one (or more) of the following constants:
  78 .TP
  79 .B SPE_EVENT_DMA_ALIGNMENT
  80 A DMA alignment error occurred.
  81 .TP
  82 .B SPE_EVENT_INVALID_DMA
  83 An invalid MFC DMA command was attempted.
  84 .\" SPE_EVENT_SPE_DATA_SEGMENT is defined, but does not seem to be generated
  85 .\" at any point (in Linux 5.9 sources).
  86 .TP
  87 .B SPE_EVENT_SPE_DATA_STORAGE
  88 A DMA storage error occurred.
  89 .TP
  90 .B SPE_EVENT_SPE_ERROR
  91 An illegal instruction was executed.
  92 .P
  93 NULL
  94 is a valid value for the
  95 .I event
  96 argument.
  97 In this case, the events will not be reported to the calling process.
  98 .SH RETURN VALUE
  99 On success,
 100 .BR spu_run ()
 101 returns the value of the
 102 .I spu_status
 103 register.
 104 On failure, it returns \-1 and sets
 105 .I errno
 106 is set to indicate the error.
 107 .P
 108 The
 109 .I spu_status
 110 register value is a bit mask of status codes and
 111 optionally a 14-bit code returned from the
 112 .B stop-and-signal
 113 instruction on the SPU.
 114 The bit masks for the status codes
 115 are:
 116 .TP
 117 .B 0x02
 118 SPU was stopped by a
 119 .B stop-and-signal
 120 instruction.
 121 .TP
 122 .B 0x04
 123 SPU was stopped by a
 124 .B halt
 125 instruction.
 126 .TP
 127 .B 0x08
 128 SPU is waiting for a channel.
 129 .TP
 130 .B 0x10
 131 SPU is in single-step mode.
 132 .TP
 133 .B 0x20
 134 SPU has tried to execute an invalid instruction.
 135 .TP
 136 .B 0x40
 137 SPU has tried to access an invalid channel.
 138 .TP
 139 .B 0x3fff0000
 140 The bits masked with this value contain the code returned from a
 141 .B stop-and-signal
 142 instruction.
 143 These bits are valid only if the 0x02 bit is set.
 144 .P
 145 If
 146 .BR spu_run ()
 147 has not returned an error, one or more bits among the lower eight
 148 ones are always set.
 149 .SH ERRORS
 150 .TP
 151 .B EBADF
 152 .I fd
 153 is not a valid file descriptor.
 154 .TP
 155 .B EFAULT
 156 .I npc
 157 is not a valid pointer, or
 158 .I event
 159 is non-NULL and an invalid pointer.
 160 .TP
 161 .B EINTR
 162 A signal occurred while
 163 .BR spu_run ()
 164 was in progress; see
 165 .BR signal (7).
 166 The
 167 .I npc
 168 value has been updated to the new program counter value if
 169 necessary.
 170 .TP
 171 .B EINVAL
 172 .I fd
 173 is not a valid file descriptor returned from
 174 .BR spu_create (2).
 175 .TP
 176 .B ENOMEM
 177 There was not enough memory available to handle a page fault
 178 resulting from a Memory Flow Controller (MFC) direct memory access.
 179 .TP
 180 .B ENOSYS
 181 The functionality is not provided by the current system, because
 182 either the hardware does not provide SPUs or the spufs module is not
 183 loaded.
 184 .SH STANDARDS
 185 Linux on PowerPC.
 186 .SH HISTORY
 187 Linux 2.6.16.
 188 .SH NOTES
 189 .BR spu_run ()
 190 is meant to be used from libraries that implement a more abstract
 191 interface to SPUs, not to be used from regular applications.
 192 See
 193 .UR http://www.bsc.es\:/projects\:/deepcomputing\:/linuxoncell/
 194 .UE
 195 for the recommended libraries.
 196 .SH EXAMPLES
 197 The following is an example of running a simple, one-instruction SPU
 198 program with the
 199 .BR spu_run ()
 200 system call.
 201 .P
 202 .\" SRC BEGIN (spu_run.c)
 203 .EX
 204 #include <err.h>
 205 #include <fcntl.h>
 206 #include <stdint.h>
 207 #include <stdio.h>
 208 #include <stdlib.h>
 209 #include <sys/types.h>
 210 #include <unistd.h>
 211 \&
 212 int main(void)
 213 {
 214     int       context, fd, spu_status;
 215     uint32_t  instruction, npc;
 216 \&
 217     context = syscall(SYS_spu_create, "/spu/example\-context", 0, 0755);
 218     if (context == \-1)
 219         err(EXIT_FAILURE, "spu_create");
 220 \&
 221     /*
 222      * Write a \[aq]stop 0x1234\[aq] instruction to the SPU\[aq]s
 223      * local store memory.
 224      */
 225     instruction = 0x00001234;
 226 \&
 227     fd = open("/spu/example\-context/mem", O_RDWR);
 228     if (fd == \-1)
 229         err(EXIT_FAILURE, "open");
 230     write(fd, &instruction, sizeof(instruction));
 231 \&
 232     /*
 233      * set npc to the starting instruction address of the
 234      * SPU program. Since we wrote the instruction at the
 235      * start of the mem file, the entry point will be 0x0.
 236      */
 237     npc = 0;
 238 \&
 239     spu_status = syscall(SYS_spu_run, context, &npc, NULL);
 240     if (spu_status == \-1)
 241         err(EXIT_FAILURE, "open");
 242 \&
 243     /*
 244      * We should see a status code of 0x12340002:
 245      *   0x00000002 (spu was stopped due to stop\-and\-signal)
 246      * | 0x12340000 (the stop\-and\-signal code)
 247      */
 248     printf("SPU Status: %#08x\en", spu_status);
 249 \&
 250     exit(EXIT_SUCCESS);
 251 }
 252 .EE
 253 .\" SRC END
 254 .\" .SH AUTHORS
 255 .\" Arnd Bergmann <arndb@de.ibm.com>, Jeremy Kerr <jk@ozlabs.org>
 256 .SH SEE ALSO
 257 .BR close (2),
 258 .BR spu_create (2),
 259 .BR capabilities (7),
 260 .BR spufs (7)