← Documents Documentation/filesystems/spufs/spu_run.rst GitHub 원문 ↗

Linux 6.18.37 · Filesystems / SPUFS

spu_run

SPU context 실행, event·status bit와 errno의 전문 번역입니다.

Source pathDocumentation/filesystems/spufs/spu_run.rst
Source versionLinux v6.18.37
TranslationDUJINLABS 전문 번역 + 해설

요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.

1. 요약·해설

원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.

요약·해설

spu_run.rst:1-138

`spu_run()`은 create fd와 `npc`에서 SPU context를 동기 실행하고, 반환 때 program counter와 status·event를 돌려준다. 병렬 실행은 caller가 별도 thread를 만들어야 한다.

SPU 실행
`spu_create()` fd`npc` instruction pointer물리 SPU에 schedule동기 실행갱신된 `npc`와 `spu_status` 반환

schedule과 반환 정보를 연결한다.

2. 영어 원문 전체

번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.

원문 전체 펼치기
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)
139

3. 한국어 전문 번역

영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.

`spu_run()` 동기 실행과 event

1-56

`spu_run(int fd, unsigned int *npc, unsigned int *event)`는 `spu_create(2)`가 반환한 fd로 특정 논리 SPU context를 지정한다. context가 물리 SPU에 schedule되면 `npc`가 가리키는 instruction pointer에서 실행을 시작한다.

실행은 동기식이어서 SPU가 실행 중인 동안 `spu_run()`은 반환하지 않는다. main CPU 또는 다른 SPU code와 병렬로 실행하려면 먼저 `pthread_create(3)` 같은 방법으로 별도 thread를 만들어야 한다. 반환 시 현재 SPU instruction pointer가 `npc`에 기록되므로 pointer를 다시 설정하지 않고 재호출할 수 있다.

`event`는 NULL이거나 확장 status code를 받을 포인터다. `SPE_EVENT_DMA_ALIGNMENT`는 DMA alignment, `SPE_EVENT_SPE_DATA_SEGMENT`는 DMA segmentation, `SPE_EVENT_SPE_DATA_STORAGE`는 DMA storage 오류를 나타낸다. NULL을 전달하면 이 오류들은 호출 process에 signal로 전달된다.

`spu_run()` event
상수의미
SPE_EVENT_DMA_ALIGNMENTDMA alignment 오류
SPE_EVENT_SPE_DATA_SEGMENTDMA segmentation 오류
SPE_EVENT_SPE_DATA_STORAGEDMA storage 오류
`event == NULL`오류를 호출 process의 signal로 전달

선택적 event 포인터로 받는 확장 오류다.

.. SPDX-License-Identifier: GPL-2.0

=======
spu_run
=======


Name
====
       spu_run - execute an spu context


Synopsis
========

       ::

            #include <sys/spu.h>

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

Description
===========
       The  spu_run system call is used on PowerPC machines that implement the
       Cell Broadband Engine Architecture in order to access Synergistic  Pro-
       cessor  Units  (SPUs).  It  uses the fd that was returned from spu_cre-
       ate(2) to address a specific SPU context. When the context gets  sched-
       uled  to a physical SPU, it starts execution at the instruction pointer
       passed in npc.

       Execution of SPU code happens synchronously, meaning that spu_run  does
       not  return  while the SPU is still running. If there is a need to exe-
       cute SPU code in parallel with other code on either  the  main  CPU  or
       other  SPUs,  you  need to create a new thread of execution first, e.g.
       using the pthread_create(3) call.

       When spu_run returns, the current value of the SPU instruction  pointer
       is  written back to npc, so you can call spu_run again without updating
       the pointers.

       event can be a NULL pointer or point to an extended  status  code  that
       gets  filled  when spu_run returns. It can be one of the following con-
       stants:

       SPE_EVENT_DMA_ALIGNMENT
              A DMA alignment error

       SPE_EVENT_SPE_DATA_SEGMENT
              A DMA segmentation error

       SPE_EVENT_SPE_DATA_STORAGE
              A DMA storage error

       If NULL is passed as the event argument, these errors will result in  a
       signal delivered to the calling process.

`spu_status` 반환 bitmask

57-89

성공 경로에서는 `spu_status` register 값을 반환하며, 오류면 `-1`과 `errno`를 반환한다. status에는 상태 bitmask와 선택적으로 SPU의 stop-and-signal instruction이 돌려준 14-bit code가 들어 있다.

`spu_status` bit
Mask상태
0x02stop-and-signal로 정지
0x04halt로 정지
0x08channel 대기
0x10single-step mode
0x20잘못된 instruction 실행 시도
0x40잘못된 channel 접근 시도
0x3fff0000stop-and-signal이 반환한 14-bit code

하위 상태 bit와 stop code mask다.

정상적인 status 반환에는 하위 8 bit 중 하나 이상이 항상 설정된다. 그렇지 않으면 `spu_run()` 자체가 error code를 반환한다.

Return Value
============
       spu_run  returns the value of the spu_status register or -1 to indicate
       an error and set errno to one of the error  codes  listed  below.   The
       spu_status  register  value  contains  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 stop-and-signal.

       0x04
              SPU was stopped by halt.

       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.

       0x3fff0000
              The  bits  masked with this value contain the code returned from
              stop-and-signal.

       There are always one or more of the lower eight bits set  or  an  error
       code is returned from spu_run.

`spu_run()` 오류

90-112
`spu_run()` errno
errno조건
EAGAIN / EWOULDBLOCKfd가 nonblocking이고 실행이 block될 상황
EBADFfd가 유효한 file descriptor가 아님
EFAULT`npc`가 유효하지 않거나 status/event pointer가 NULL도 유효 포인터도 아님
EINTR실행 중 signal 발생; 필요하면 `npc`는 새 program counter로 갱신
EINVALfd가 `spu_create(2)`에서 반환된 descriptor가 아님
ENOMEMMFC DMA로 인한 page fault 처리 메모리 부족
ENOSYSSPU hardware가 없거나 spufs module이 load되지 않음

호출·pointer·resource 오류를 구분한다.

Errors
======
       EAGAIN or EWOULDBLOCK
              fd is in non-blocking mode and spu_run would block.

       EBADF  fd is not a valid file descriptor.

       EFAULT npc is not a valid pointer or status is neither NULL nor a valid
              pointer.

       EINTR  A signal occurred while spu_run was in progress.  The npc  value
              has  been updated to the new program counter value if necessary.

       EINVAL fd is not a file descriptor returned from spu_create(2).

       ENOMEM Insufficient memory was available to handle a page fault result-
              ing from an MFC direct memory access.

       ENOSYS the functionality is not provided by the current system, because
              either the hardware does not provide SPUs or the spufs module is
              not loaded.

사용 범위·이식성·관련 문서

113-138

`spu_run()`도 일반 application보다 SPU 추상화 library에서 사용하도록 의도됐다. 권장 library는 Linux on Cell 프로젝트를 참조한다.

이 syscall은 Linux 전용이며 ppc64 architecture에만 구현되어 이식성이 없다. 문서 기능 일부가 아직 구현되지 않았을 수 있다. 저자는 Arnd Bergmann이며 관련 문서는 `capabilities(7)`, `close(2)`, `spu_create(2)`, `spufs(7)`이다.

`spu_run()` 적용 범위
항목내용
권장 호출자SPU 추상화 library
Architectureppc64
표준Linux-specific
관련 API`spu_create(2)`와 `spufs(7)`

create syscall과 같은 플랫폼 제약을 갖는다.

Notes
=====
       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  http://www.bsc.es/projects/deepcomputing/linuxoncell/ for the rec-
       ommended libraries.


Conforming to
=============
       This call is Linux specific and only implemented by the ppc64 architec-
       ture. Programs using this system call are not portable.


Bugs
====
       The code does not yet fully implement all features lined out here.


Author
======
       Arnd Bergmann <arndb@de.ibm.com>

See Also
========
       capabilities(7), close(2), spu_create(2), spufs(7)