Local netbeans changes, 11.3 and jdk location.
[zcl] / README
1
2 foreign-abi branch note
3 -----------------------
4
5 This is still work in progress, expect breakage, out of date doco,
6 other issues.
7
8 Various native support code is in the temporary package api.*,
9 eventually to be moved to a new nativez.
10
11 I've added 'run-X' targets to run the demos.  Arguments are passed
12 using ARGV.
13
14 make run-clinfo
15 make run-Mandelbrot
16 make run-Mandelbrot ARGV="--gamma=15 --rotate=0"
17
18
19 INTRODUCTION
20 ------------
21
22 This is a direct Java binding for OpenCL 2.1 and Java 13.
23
24 I originally wrote it over a few days mostly just to pass the time and
25 the goals were:
26
27  * Minimal C and Java code;
28  * Lightweight Java objects;
29  * Feature complete for every OpenCL api;
30  * Follow the OpenCL api closely;
31  * Use primitive Java types instead of or as well as ByteBuffers
32    where it makes sense;
33  * Object-oriented and type-safe;
34  * Robust and fault-tolerant;
35  * Erring on the side of usability when constraints conflict;
36  * Simple to build.
37
38 The approach taken was to put most of the code into C so that
39 32/64-bit portability is provided soley by the non-java code.  This
40 simplifies the Java and doesn't add much complication to the C code.
41 To this end a 64-bit type is used on all platforms to store or
42 transfer values which may change across platforms (void * and size_t).
43
44 The Java instances of each OpenCL object are effectively just empty
45 interfaces - they hold nothing but the pointer to the underlying
46 object and pass all function calls to the jni layer.
47
48 All API enty points are defined including event callbacks and the
49 ability to write native kernels in Java.
50
51 As with any 'simple' project, it's grown to be somewhat complex but it
52 is still basic and portable code which is easy to build and maintain.
53
54 There have been a couple of important additions to the feature list:
55
56  * Object references are now globally unqiue;
57  * Automatic and manual resource reclaimation via garbage collection;
58  * Lambda interfaces (experimental);
59  * Runtime API version checking.
60
61 These all go hand in hand and allow for simplified application
62 development with a few caveats.  Garbage detection is via referent
63 queues for efficiency.
64
65 PLATFORMS
66 ---------
67
68 As the binding is mostly native interfaces the code is platform
69 specific.
70
71 The only supported target is 64-bit GNU systems and is obviously the
72 default when running make.  But it should also compile on 32-bit
73 platforms in a straightforward manner.
74
75 As a NON-SUPPORTED target, it can be cross-compiled for windows-amd64.
76 It is not supported.
77
78 The library supports full OpenCL 2.1 and two OpenGL related
79 extensions.
80
81 COMPILING
82 ---------
83
84 Standard GNU development tools and a Java JDK are required in order to
85 compile zcl (ant is not used).  perl and cproto are also required.
86 Java 13 is the baseline used but JDK 9+ may work.
87
88 The prequisitve project notzed.nativez must also have previously been
89 compiled and will be automatically used if it is present in the
90 directory above this one (../nativez/).
91
92 Copy config.make.in to config.make and edit for configuration parameters.
93
94 The jni source includes the KHR OpenCL headers so an OpenCL SDK is not
95 required but one may be used instead by defining CL_HOME on the
96 command line.
97
98 Build everything for default target of linux-amd64:
99
100 $ make
101
102 Build everything for a specific target:
103
104 $ make TARGET=<target>
105
106 All intermediate and final results are place in `bin/'.
107
108 `bin/<target>/lib/<module>.jar'    Modular jar for ide.
109 `bin/<target>/lib/*.so'            Platform specific
110 `bin/<target>/bin/*.dll'            runtime libraries.
111
112 `bin/<target>/jmods/<module>.jmod' Target specific .jmod.
113
114 $ make bin
115
116 Build everything but the jars and jmods.
117
118 $ make dist
119
120 Create a source archive.  The source is found via $(find) so
121 this will include any droppings.
122
123 OPENCL VERSION
124 --------------
125
126 For the most part it is up to applications to determine the OpenCL
127 version in use and call functions appropriately.
128
129 As of version 0.6 runtime version checking has been implemented for
130 most api calls for version 2.0 or later.  The version check is
131 relatively cheap but has not been implemented on all versioned
132 interfaces for performance reasons (i.e. CLKernel).
133
134 The binding should be compilable against OpenCL headers from 1.0 or
135 later, although as the headers are included this is not required (or
136 tested).
137
138 Linking
139 - - - -
140
141 As of 0.5 the library only uses dynamic linking.  A function table
142 is loaded at init time and all methods are invoked via the table.
143
144 A script is used to generate the function table from CL/cl.h.  It
145 assumes a very specific formatting.
146
147 Although it is not a reliable indicator of platform support, NULL
148 function pointers are protected against.
149
150 Currently the OpenCL version the SDK the library is compiled against
151 sets the highest supported API level and by default it uses the
152 bundled headers which is at OpenCL 2.1.
153
154 USING
155 -----
156
157 If not using .jmod, the directory containing libzcl.so must be added
158 to the java.library.path or LD_LIBRARY_PATH during execution. The same
159 goes for libnativez.so.
160
161 The API follows the C api closely together with some convenient
162 property getters and some overloaded functions for native arrays.
163
164 Setting the environment variable ZCL_SYNC to non-zero will print all
165 kernel executions and force a clFlush() and clFinish() at each.
166
167 clinfo
168 ------
169
170 A simple and incomplete implementation of the 'clinfo' tool is part of
171 the package.  After building it can be used as a basic functionality
172 test.
173
174 $ LD_LIBRARY_PATH=../nativez/bin/notzed.nativez/linux-amd64/lib:bin/notzed.zcl/linux-amd64/lib \
175   java --module-path bin/modules:../nativez/bin/modules \
176   -m notzed.zcl.demo/au.notzed.zcl.tools.clinfo
177
178 Note that clinfo will crash on coprthr 1.6.0 due to a bug.
179
180 STATUS
181 ------
182
183 As of 0.5 this should be considered beta quality.  It is in use for
184 prototype development in a research context.
185
186 It implements every base OpenCL 2.1 api, even some that aren't very
187 useful for Java.  All deprecated functions and constants from
188 OpenCL 2.1 are (should be) correctly marked as such.
189
190 Most interfaces are protected from null pointers, bad ranges, and
191 runtime failures.  This will protect against many common api errors
192 with Java exceptions but it is still (easily) possible to crash
193 applications with no obvious cause.
194
195 Two KHR extensions have been (mostly) implemented: GLSharing and
196 GLEvent.  They reside in the au.notzed.zcl.khr namespace so have
197 dropped some mess from the names.
198
199 Beyond property getters there are few 'helper' functions so that
200 methods take all the parameters of their C counterparts.  This is not
201 always terribly convenient.
202
203 Documentation is limited.
204
205 None of OpenCL 2.1 has been tested and may be broken.
206
207 Automatic Resource Reclamation
208 - - - - - - - - - - - - - - - -
209
210 All objects should be automatically garbage collected.  This is mostly
211 automagic but in some cases requires the user to maintain references
212 to parent objects explicitly.  Objects may also be manually disposed
213 of using release().  It is not recommended that retain() be used from
214 Java at all.
215
216 This automatic resource reclaimation comes with the same usual caveats
217 with native resources - the impedence mismatch between Java and native
218 can cause allocation problems.  Somebody Else's Problem (it seems to
219 work quite well in practice).
220
221 Primitive arrays buffers
222 - - - - - - - - - - - - -
223
224 There is support for passing primitive arrays to functions which would
225 otherwise only take a direct ByteBuffer.
226
227 This (currently) forces any enqueue operations to blocking mode and
228 also bloats out the api and implementation - so the limited
229 convenience they provide might not be worth their cost.
230
231 Note that this only affects 'asynchronous memory' and does not affect
232 small arrays used for things like dimensions, ranges, or patterns
233 which are copied by the jni and OpenCL API at method invocation time.
234
235 Lambdas
236 - - - -
237
238 A design-in-progress lambda based mechanism for encapsulating
239 enqueuable tasks is defined by CLTask.  Some operations have been
240 added to the target objects such as ofRead(byte[]) to the CLBuffer
241 interface.
242
243 The primary goal of this interface is to provide a cleaner api by
244 removing the need to pass a pair of CLEventLists and a CLCommandQueue
245 to every work function.  As a side-effect of garbage collection and
246 features of lambdas it provides extra convenience as well.
247
248 For example, rather than calling this every time:
249
250  q.enqueueReadBuffer(src, false, 0, size, dst, 0, null, null);
251  q.enqueueReadBuffer(src, false, 0, size, dst, 0, waits, events);
252
253 One can instead do this:
254
255  // this once
256  CLTask task = src.ofRead(dst, size);
257
258  // multiple times
259  q.offer(task);
260  q.offer(task, waits, events);
261
262 And so on, with a few other little lambda treats along the way like
263 'andThen()'.
264
265 Although this mechanism allows for flexible "pre-compiled" expressions
266 the inability to change parameters are invocation time have proved to
267 be somewhat limiting.  This is still work in progress.
268
269 Extensions
270 ----------
271
272 OpenCL extensions and function entry points must be resolved via the
273 CLPlatform.
274
275 Extension interfaces are handled by a two-layer mechanism.  Firstly a
276 Java/JNI combination implements one specific extension and contains
277 all constants and entry points for the extension.  The java object
278 must derive from CLExtension.  These may be used as is but are
279 inconvenient.
280
281 So relevent entry points are then added to each target object
282 (i.e. first parameter of function) which handles the extension lookup.
283 Each object which may have extented function on it must derive from
284 CLExtendable which provides an efficient way to cache and resolve the
285 extension object.
286
287 Core extension objects are instantiated via CLPlatform but may be
288 created by independent JNI code and used without modifying the core
289 api.
290
291 They are currently never unloaded.  There may be some changes but the
292 current design seems sufficient.
293
294 FUTURE PLANS
295 ------------
296
297 I'm not sure now, I haven't been using it much and there's zero
298 outside interest.  CUDA is all the fucked-up-rage these days.
299
300 I might look into Vulkan, which has significant overlap although not
301 such a simple API.
302
303 LICENSE
304 -------
305
306 Most of the code is licensed under GNU General Public License version
307 3, see COPYING for full details.
308
309     Copyright (C) 2014,2015 Michael Zucchi
310
311     This program is free software: you can redistribute it and/or
312     modify it under the terms of the GNU General Public License as
313     published by the Free Software Foundation, either version 3 of the
314     License, or (at your option) any later version.
315
316     This program is distributed in the hope that it will be useful,
317     but WITHOUT ANY WARRANTY; without even the implied warranty of
318     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
319     General Public License for more details.
320
321     You should have received a copy of the GNU General Public License
322     along with this program.  If not, see
323     <http://www.gnu.org/licenses/>.
324
325 Certain content was copied from cl.h from OpenCL 1.2, these files
326 include the following header:
327
328     Copyright (c) 2008 - 2012 The Khronos Group Inc.
329
330     Permission is hereby granted, free of charge, to any person
331     obtaining a copy of this software and/or associated documentation
332     files (the "Materials"), to deal in the Materials without
333     restriction, including without limitation the rights to use, copy,
334     modify, merge, publish, distribute, sublicense, and/or sell copies
335     of the Materials, and to permit persons to whom the Materials are
336     furnished to do so, subject to the following conditions:
337
338     The above copyright notice and this permission notice shall be
339     included in all copies or substantial portions of the Materials.
340
341     THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
342     EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
343     MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
344     NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
345     HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
346     WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
347     OUT OF OR IN CONNECTION WITH THE MATERIALS OR THE USE OR OTHER
348     DEALINGS IN THE MATERIALS.