0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 =======
0004 spu_run
0005 =======
0006
0007
0008 Name
0009 ====
0010 spu_run - execute an spu context
0011
0012
0013 Synopsis
0014 ========
0015
0016 ::
0017
0018 #include <sys/spu.h>
0019
0020 int spu_run(int fd, unsigned int *npc, unsigned int *event);
0021
0022 Description
0023 ===========
0024 The spu_run system call is used on PowerPC machines that implement the
0025 Cell Broadband Engine Architecture in order to access Synergistic Pro-
0026 cessor Units (SPUs). It uses the fd that was returned from spu_cre-
0027 ate(2) to address a specific SPU context. When the context gets sched-
0028 uled to a physical SPU, it starts execution at the instruction pointer
0029 passed in npc.
0030
0031 Execution of SPU code happens synchronously, meaning that spu_run does
0032 not return while the SPU is still running. If there is a need to exe-
0033 cute SPU code in parallel with other code on either the main CPU or
0034 other SPUs, you need to create a new thread of execution first, e.g.
0035 using the pthread_create(3) call.
0036
0037 When spu_run returns, the current value of the SPU instruction pointer
0038 is written back to npc, so you can call spu_run again without updating
0039 the pointers.
0040
0041 event can be a NULL pointer or point to an extended status code that
0042 gets filled when spu_run returns. It can be one of the following con-
0043 stants:
0044
0045 SPE_EVENT_DMA_ALIGNMENT
0046 A DMA alignment error
0047
0048 SPE_EVENT_SPE_DATA_SEGMENT
0049 A DMA segmentation error
0050
0051 SPE_EVENT_SPE_DATA_STORAGE
0052 A DMA storage error
0053
0054 If NULL is passed as the event argument, these errors will result in a
0055 signal delivered to the calling process.
0056
0057 Return Value
0058 ============
0059 spu_run returns the value of the spu_status register or -1 to indicate
0060 an error and set errno to one of the error codes listed below. The
0061 spu_status register value contains a bit mask of status codes and
0062 optionally a 14 bit code returned from the stop-and-signal instruction
0063 on the SPU. The bit masks for the status codes are:
0064
0065 0x02
0066 SPU was stopped by stop-and-signal.
0067
0068 0x04
0069 SPU was stopped by halt.
0070
0071 0x08
0072 SPU is waiting for a channel.
0073
0074 0x10
0075 SPU is in single-step mode.
0076
0077 0x20
0078 SPU has tried to execute an invalid instruction.
0079
0080 0x40
0081 SPU has tried to access an invalid channel.
0082
0083 0x3fff0000
0084 The bits masked with this value contain the code returned from
0085 stop-and-signal.
0086
0087 There are always one or more of the lower eight bits set or an error
0088 code is returned from spu_run.
0089
0090 Errors
0091 ======
0092 EAGAIN or EWOULDBLOCK
0093 fd is in non-blocking mode and spu_run would block.
0094
0095 EBADF fd is not a valid file descriptor.
0096
0097 EFAULT npc is not a valid pointer or status is neither NULL nor a valid
0098 pointer.
0099
0100 EINTR A signal occurred while spu_run was in progress. The npc value
0101 has been updated to the new program counter value if necessary.
0102
0103 EINVAL fd is not a file descriptor returned from spu_create(2).
0104
0105 ENOMEM Insufficient memory was available to handle a page fault result-
0106 ing from an MFC direct memory access.
0107
0108 ENOSYS the functionality is not provided by the current system, because
0109 either the hardware does not provide SPUs or the spufs module is
0110 not loaded.
0111
0112
0113 Notes
0114 =====
0115 spu_run is meant to be used from libraries that implement a more
0116 abstract interface to SPUs, not to be used from regular applications.
0117 See http://www.bsc.es/projects/deepcomputing/linuxoncell/ for the rec-
0118 ommended libraries.
0119
0120
0121 Conforming to
0122 =============
0123 This call is Linux specific and only implemented by the ppc64 architec-
0124 ture. Programs using this system call are not portable.
0125
0126
0127 Bugs
0128 ====
0129 The code does not yet fully implement all features lined out here.
0130
0131
0132 Author
0133 ======
0134 Arnd Bergmann <arndb@de.ibm.com>
0135
0136 See Also
0137 ========
0138 capabilities(7), close(2), spu_create(2), spufs(7)
