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