SPU_RUN(2)                (2020-11-01)                 SPU_RUN(2)

          spu_run - execute an SPU context

          #include <sys/spu.h>

          int spu_run(int fd, unsigned int *npc, unsigned int *event

          Note: There is no glibc wrapper for this system call; see

          The spu_run() system call is used on PowerPC machines that
          implement the Cell Broadband Engine Architecture in order to
          access Synergistic Processor Units (SPUs).  The fd argument
          is a file descriptor returned by spu_create(2) that refers
          to a specific SPU context.  When the context gets scheduled
          to a physical SPU, it starts execution at the instruction
          pointer passed in npc.

          Execution of SPU code happens synchronously, meaning that
          spu_run() blocks while the SPU is still running.  If there
          is a need to execute SPU code in parallel with other code on
          either the main CPU or other SPUs, a new thread of execution
          must be created first (e.g., using pthread_create(3)).

          When spu_run() returns, the current value of the SPU program
          counter is written to npc, so successive calls to spu_run()
          can use the same npc pointer.

          The event argument provides a buffer for an extended status
          code.  If the SPU context was created with the
          SPU_CREATE_EVENTS_ENABLED flag, then this buffer is popu-
          lated by the Linux kernel before spu_run() returns.

          The status code may be one (or more) of the following con-

               A DMA alignment error occurred.

               An invalid MFC DMA command was attempted.

               A DMA storage error occurred.

               An illegal instruction was executed.

     Page 1                        Linux             (printed 5/24/22)

     SPU_RUN(2)                (2020-11-01)                 SPU_RUN(2)

          NULL is a valid value for the event argument.  In this case,
          the events will not be reported to the calling process.

          On success, spu_run() returns the value of the spu_status
          register.  On error, it returns -1 and sets errno to one of
          the error codes listed below.

          The spu_status register value is a bit mask of status codes
          and optionally a 14-bit code returned from the
          stop-and-signal instruction on the SPU.  The bit masks for
          the status codes are:

          0x02 SPU was stopped by a stop-and-signal instruction.

          0x04 SPU was stopped by a halt instruction.

          0x08 SPU is waiting for a channel.

          0x10 SPU is in single-step mode.

          0x20 SPU has tried to execute an invalid instruction.

          0x40 SPU has tried to access an invalid channel.

               The bits masked with this value contain the code
               returned from a stop-and-signal instruction.  These
               bits are valid only if the 0x02 bit is set.

          If spu_run() has not returned an error, one or more bits
          among the lower eight ones are always set.

               fd is not a valid file descriptor.

               npc is not a valid pointer, or event is non-NULL and an
               invalid pointer.

               A signal occurred while spu_run() was in progress; see
               signal(7).  The npc value has been updated to the new
               program counter value if necessary.

               fd is not a valid file descriptor returned from

               There was not enough memory available to handle a page

     Page 2                        Linux             (printed 5/24/22)

     SPU_RUN(2)                (2020-11-01)                 SPU_RUN(2)

               fault resulting from a Memory Flow Controller (MFC)
               direct memory access.

               The functionality is not provided by the current sys-
               tem, because either the hardware does not provide SPUs
               or the spufs module is not loaded.

          The spu_run() system call was added to Linux in kernel

          This call is Linux-specific and implemented only by the Pow-
          erPC architecture.  Programs using this system call are not

          Glibc does not provide a wrapper for this system call; call
          it using syscall(2).  Note however, that spu_run() is meant
          to be used from libraries that implement a more abstract
          interface to SPUs, not to be used from regular applications.
          See for the recommended libraries.

          The following is an example of running a simple, one-
          instruction SPU program with the spu_run() system call.

          #include <stdlib.h>
          #include <stdint.h>
          #include <unistd.h>
          #include <stdio.h>
          #include <sys/types.h>
          #include <fcntl.h>

          #define handle_error(msg) \
              do { perror(msg); exit(EXIT_FAILURE); } while (0)

          int main(void)
              int context, fd, spu_status;
              uint32_t instruction, npc;

              context = spu_create("/spu/example-context", 0, 0755);
              if (context == -1)

              /* write a aqstop 0x1234aq instruction to the SPUaqs
               * local store memory
              instruction = 0x00001234;

     Page 3                        Linux             (printed 5/24/22)

     SPU_RUN(2)                (2020-11-01)                 SPU_RUN(2)

              fd = open("/spu/example-context/mem", O_RDWR);
              if (fd == -1)
              write(fd, &instruction, sizeof(instruction));

              /* set npc to the starting instruction address of the
               * SPU program. Since we wrote the instruction at the
               * start of the mem file, the entry point will be 0x0
              npc = 0;

              spu_status = spu_run(context, &npc, NULL);
              if (spu_status == -1)

              /* we should see a status code of 0x1234002:
               *   0x00000002 (spu was stopped due to stop-and-signal)
               * | 0x12340000 (the stop-and-signal code)
              printf("SPU Status: %#08x\n", spu_status);


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

          This page is part of release 5.10 of the Linux man-pages
          project.  A description of the project, information about
          reporting bugs, and the latest version of this page, can be
          found at https://www.kernel.org/doc/man-pages/.

     Page 4                        Linux             (printed 5/24/22)