1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 ========== 3 ==========
4 spu_create 4 spu_create
5 ========== 5 ==========
6 6
7 Name 7 Name
8 ==== 8 ====
9 spu_create - create a new spu context 9 spu_create - create a new spu context
10 10
11 11
12 Synopsis 12 Synopsis
13 ======== 13 ========
14 14
15 :: 15 ::
16 16
17 #include <sys/types.h> 17 #include <sys/types.h>
18 #include <sys/spu.h> 18 #include <sys/spu.h>
19 19
20 int spu_create(const char *pathname, 20 int spu_create(const char *pathname, int flags, mode_t mode);
21 21
22 Description 22 Description
23 =========== 23 ===========
24 The spu_create system call is used on 24 The spu_create system call is used on PowerPC machines that implement
25 the Cell Broadband Engine Architecture 25 the Cell Broadband Engine Architecture in order to access Synergistic
26 Processor Units (SPUs). It creates a n 26 Processor Units (SPUs). It creates a new logical context for an SPU in
27 pathname and returns a handle to associ 27 pathname and returns a handle to associated with it. pathname must
28 point to a non-existing directory in 28 point to a non-existing directory in the mount point of the SPU file
29 system (spufs). When spu_create is suc 29 system (spufs). When spu_create is successful, a directory gets cre-
30 ated on pathname and it is populated wi 30 ated on pathname and it is populated with files.
31 31
32 The returned file handle can only be 32 The returned file handle can only be passed to spu_run(2) or closed,
33 other operations are not defined on it. 33 other operations are not defined on it. When it is closed, all associ-
34 ated directory entries in spufs are re 34 ated directory entries in spufs are removed. When the last file handle
35 pointing either inside of the contex 35 pointing either inside of the context directory or to this file
36 descriptor is closed, the logical SPU c 36 descriptor is closed, the logical SPU context is destroyed.
37 37
38 The parameter flags can be zero or any 38 The parameter flags can be zero or any bitwise or'd combination of the
39 following constants: 39 following constants:
40 40
41 SPU_RAWIO 41 SPU_RAWIO
42 Allow mapping of some of the har 42 Allow mapping of some of the hardware registers of the SPU into
43 user space. This flag requires t 43 user space. This flag requires the CAP_SYS_RAWIO capability, see
44 capabilities(7). 44 capabilities(7).
45 45
46 The mode parameter specifies the permis 46 The mode parameter specifies the permissions used for creating the new
47 directory in spufs. mode is modifie 47 directory in spufs. mode is modified with the user's umask(2) value
48 and then used for both the directory an 48 and then used for both the directory and the files contained in it. The
49 file permissions mask out some more bit 49 file permissions mask out some more bits of mode because they typically
50 support only read or write access. See 50 support only read or write access. See stat(2) for a full list of the
51 possible mode values. 51 possible mode values.
52 52
53 53
54 Return Value 54 Return Value
55 ============ 55 ============
56 spu_create returns a new file descript 56 spu_create returns a new file descriptor. It may return -1 to indicate
57 an error condition and set errno to on 57 an error condition and set errno to one of the error codes listed
58 below. 58 below.
59 59
60 60
61 Errors 61 Errors
62 ====== 62 ======
63 EACCES 63 EACCES
64 The current user does not have 64 The current user does not have write access on the spufs mount
65 point. 65 point.
66 66
67 EEXIST An SPU context already exists at 67 EEXIST An SPU context already exists at the given path name.
68 68
69 EFAULT pathname is not a valid string p 69 EFAULT pathname is not a valid string pointer in the current address
70 space. 70 space.
71 71
72 EINVAL pathname is not a directory in t 72 EINVAL pathname is not a directory in the spufs mount point.
73 73
74 ELOOP Too many symlinks were found whi 74 ELOOP Too many symlinks were found while resolving pathname.
75 75
76 EMFILE The process has reached its maxi 76 EMFILE The process has reached its maximum open file limit.
77 77
78 ENAMETOOLONG 78 ENAMETOOLONG
79 pathname was too long. 79 pathname was too long.
80 80
81 ENFILE The system has reached the globa 81 ENFILE The system has reached the global open file limit.
82 82
83 ENOENT Part of pathname could not be re 83 ENOENT Part of pathname could not be resolved.
84 84
85 ENOMEM The kernel could not allocate al 85 ENOMEM The kernel could not allocate all resources required.
86 86
87 ENOSPC There are not enough SPU res 87 ENOSPC There are not enough SPU resources available to create a new
88 context or the user specific lim 88 context or the user specific limit for the number of SPU con-
89 texts has been reached. 89 texts has been reached.
90 90
91 ENOSYS the functionality is not provide 91 ENOSYS the functionality is not provided by the current system, because
92 either the hardware does not pro 92 either the hardware does not provide SPUs or the spufs module is
93 not loaded. 93 not loaded.
94 94
95 ENOTDIR 95 ENOTDIR
96 A part of pathname is not a dire 96 A part of pathname is not a directory.
97 97
98 98
99 99
100 Notes 100 Notes
101 ===== 101 =====
102 spu_create is meant to be used from 102 spu_create is meant to be used from libraries that implement a more
103 abstract interface to SPUs, not to be u 103 abstract interface to SPUs, not to be used from regular applications.
104 See http://www.bsc.es/projects/deepcom 104 See http://www.bsc.es/projects/deepcomputing/linuxoncell/ for the rec-
105 ommended libraries. 105 ommended libraries.
106 106
107 107
108 Files 108 Files
109 ===== 109 =====
110 pathname must point to a location benea 110 pathname must point to a location beneath the mount point of spufs. By
111 convention, it gets mounted in /spu. 111 convention, it gets mounted in /spu.
112 112
113 113
114 Conforming to 114 Conforming to
115 ============= 115 =============
116 This call is Linux specific and only im 116 This call is Linux specific and only implemented by the ppc64 architec-
117 ture. Programs using this system call a 117 ture. Programs using this system call are not portable.
118 118
119 119
120 Bugs 120 Bugs
121 ==== 121 ====
122 The code does not yet fully implement a 122 The code does not yet fully implement all features lined out here.
123 123
124 124
125 Author 125 Author
126 ====== 126 ======
127 Arnd Bergmann <arndb@de.ibm.com> 127 Arnd Bergmann <arndb@de.ibm.com>
128 128
129 See Also 129 See Also
130 ======== 130 ========
131 capabilities(7), close(2), spu_run(2), 131 capabilities(7), close(2), spu_run(2), spufs(7)
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.