Documentation/filesystems/spufs/spu_run.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 =======
   4 spu_run
   5 =======
   6
   7
   8 Name
   9 ====
  10        spu_run - execute an spu context
  11
  12
  13 Synopsis
  14 ========
  15
  16        ::
  17
  18             #include <sys/spu.h>
  19
  20             int spu_run(int fd, unsigned int *npc, unsigned int *event);
  21
  22 Description
  23 ===========
  24        The  spu_run system call is used on PowerPC machines that implement the
  25        Cell Broadband Engine Architecture in order to access Synergistic  Pro-
  26        cessor  Units  (SPUs).  It  uses the fd that was returned from spu_cre-
  27        ate(2) to address a specific SPU context. When the context gets  sched-
  28        uled  to a physical SPU, it starts execution at the instruction pointer
  29        passed in npc.
  30
  31        Execution of SPU code happens synchronously, meaning that spu_run  does
  32        not  return  while the SPU is still running. If there is a need to exe-
  33        cute SPU code in parallel with other code on either  the  main  CPU  or
  34        other  SPUs,  you  need to create a new thread of execution first, e.g.
  35        using the pthread_create(3) call.
  36
  37        When spu_run returns, the current value of the SPU instruction  pointer
  38        is  written back to npc, so you can call spu_run again without updating
  39        the pointers.
  40
  41        event can be a NULL pointer or point to an extended  status  code  that
  42        gets  filled  when spu_run returns. It can be one of the following con-
  43        stants:
  44
  45        SPE_EVENT_DMA_ALIGNMENT
  46               A DMA alignment error
  47
  48        SPE_EVENT_SPE_DATA_SEGMENT
  49               A DMA segmentation error
  50
  51        SPE_EVENT_SPE_DATA_STORAGE
  52               A DMA storage error
  53
  54        If NULL is passed as the event argument, these errors will result in  a
  55        signal delivered to the calling process.
  56
  57 Return Value
  58 ============
  59        spu_run  returns the value of the spu_status register or -1 to indicate
  60        an error and set errno to one of the error  codes  listed  below.   The
  61        spu_status  register  value  contains  a  bit  mask of status codes and
  62        optionally a 14 bit code returned from the stop-and-signal  instruction
  63        on the SPU. The bit masks for the status codes are:
  64
  65        0x02
  66               SPU was stopped by stop-and-signal.
  67
  68        0x04
  69               SPU was stopped by halt.
  70
  71        0x08
  72               SPU is waiting for a channel.
  73
  74        0x10
  75               SPU is in single-step mode.
  76
  77        0x20
  78               SPU has tried to execute an invalid instruction.
  79
  80        0x40
  81               SPU has tried to access an invalid channel.
  82
  83        0x3fff0000
  84               The  bits  masked with this value contain the code returned from
  85               stop-and-signal.
  86
  87        There are always one or more of the lower eight bits set  or  an  error
  88        code is returned from spu_run.
  89
  90 Errors
  91 ======
  92        EAGAIN or EWOULDBLOCK
  93               fd is in non-blocking mode and spu_run would block.
  94
  95        EBADF  fd is not a valid file descriptor.
  96
  97        EFAULT npc is not a valid pointer or status is neither NULL nor a valid
  98               pointer.
  99
 100        EINTR  A signal occurred while spu_run was in progress.  The npc  value
 101               has  been updated to the new program counter value if necessary.
 102
 103        EINVAL fd is not a file descriptor returned from spu_create(2).
 104
 105        ENOMEM Insufficient memory was available to handle a page fault result-
 106               ing from an MFC direct memory access.
 107
 108        ENOSYS the functionality is not provided by the current system, because
 109               either the hardware does not provide SPUs or the spufs module is
 110               not loaded.
 111
 112
 113 Notes
 114 =====
 115        spu_run  is  meant  to  be  used  from  libraries that implement a more
 116        abstract interface to SPUs, not to be used from  regular  applications.
 117        See  http://www.bsc.es/projects/deepcomputing/linuxoncell/ for the rec-
 118        ommended libraries.
 119
 120
 121 Conforming to
 122 =============
 123        This call is Linux specific and only implemented by the ppc64 architec-
 124        ture. Programs using this system call are not portable.
 125
 126
 127 Bugs
 128 ====
 129        The code does not yet fully implement all features lined out here.
 130
 131
 132 Author
 133 ======
 134        Arnd Bergmann <arndb@de.ibm.com>
 135
 136 See Also
 137 ========
 138        capabilities(7), close(2), spu_create(2), spufs(7)