1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
|
This directory tree holds Portable OpenCL (pocl), a (still in-development)
implementation of OpenCL standard which can be easily adapted for new targets.
The file INSTALL in this directory says how to build and install packages
which use the GNU build system, most of which is valid for the pocl
distribution.
This file provides additional information on required software packages,
special configure flags pocl might use, running pocl examples and using
pocl as the OpenCL implementation with any program that uses OpenCL. It
also describes the "standalone compilation mode" which might be used to
statically link kernels with the host program, and how to call any
host C library or syscall in your kernels which might be useful for
kernel debugging (see HOST LIBRARY CALLS).
EXAMPLES
After the build is complete, a number of examples are ready to be run on
the subdirectories under examples/. To run them, just go to each directory
and run the executable there (executable name matches subdirectory name).
example1 Dot product example from OpenCL specification
example2 Matrix transpose example from OpenCL specification
barriers Simple barrier synchronization exampls
forloops Simple example wth for loops inside the kernel
standalone Non-executable standalone example (see STANDALONE section)
trig Example using various trigonometric functions
scalarwave Example evolving the scalar wave equation
LINKING YOUR PROGRAM WITH POCL
During installation, pocl places a copy of standard OpenCL headers in
<prefix>/include/CL, and the host runtime OpenCL library (libOpenCL) in
<prefix>/lib.
Passing the appropriate linker flags is enough to use pocl in your
program. However, please bear in mind that:
1. The current distribution only supports one device, "native",
which runs the kernels in the host system.
2. Current implementation of both host and kernel runtime libraries
is far for complete. If your program uses any of the unimplemented
API calls, it will not work. Please implement the mssing APIs
when you need them and submit us a patch :)
The pkg-config tool is used to locate the libraries and headers in
the installation directory.
Example of compiling an OpenCL host program against pocl using
the pkg-config:
gcc example1.c -o example `pkg-config --libs --cflags pocl`
STANDALONE
The "standalone compilation mode" is especially useful for embedded standalone
platforms which do not include an operating system with a dynamic linker
and still want to run OpenCL programs to exploit the language's parallelism.
The key idea in the standalone mode is to link the OpenCL kernels statically
to the host program and make the kernels appear in the "kernel registry" of
the host API so they can be lauched from the main program without needing to
invoke the runtime kernel compilation.
The original targets of this method are the application-specific TTA processors
designed with the TTA-Based Co-design Environment (http://tce.cs.tut.fi) which
now uses pocl for kernel compilation. TCE's compiler driver script tcecc serves
as an example how to register and launch the kernels seamlessly in the
compilation/linkage chain of standalone OpenCL programs.
The 'pocl-standalone' script can be used to compile OpenCL C kernels separately
to be linked with the main program in this setting.
HOST LIBRARY CALLS
When using the "native" device that runs the kernels on the host (after
statically replicating their work items), the kernels might use any
library or system call in the host. The examples "barriers" and "forloops"
show how to call "printf" inside the kernel, but any other host function
can be called as well. This can prove quite useful when debugging OpenCL
kernels.
KERNEL REPLICATION
(todo)
INSTALLABLE CLIENT DRIVER (ICD)
Pocl is built with the ICD extensions of OpenCL by default. This allows you
to have several OpenCL implementations concurrently on your computer, and select
the one to use at runtime by selecting the corresponding cl_platform. ICD support
can be disabled by adding the flag
--disable-icd
to the ./configure script.
In case you also give the --prefix=$INSTALL option to ./configure, you need to
copy the icd file to where your ICD loader finds it:
cp $INSTALL/etc/OpenCL/vendors/pocl.icd /etc/OpenCL/vendors/pocl.icd
Pocl does not supply a ICD loader implementation. At least the OpenCL implementations
of nVidia, AMD and FreeOCL provide a ICD loader.
|