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