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 * ======== ti.sdo.opencl ========
41 * OpenCL API Implementation
42 *
43 * OpenCL is a programming framework for heterogeneous compute resources
44 * developed by the Khronos group. It allows a host processor to execute
45 * code on multiple device processors.
46 *
47 * This implementation of the OpenCL specification supports only the
48 * task-parallel model. Please note, this implementation is still under
49 * development.
50 *
51 * The following diagram illustrates an OpenCL application architecture.
52 *
53 * @p(html)
54 * <br>
55 * <img src="./doc-files/AppArch.png" />
56 * <br>
57 * @p
58 *
59 * The application, running on the host processor, makes OpenCL API
60 * calls to execute kernel functions on the device processor. In this
61 * example, the application is running on the C674x processor and the
62 * kernel functions are executed on the ARP32 processor. The application
63 * provides the thread (red circle) which calls the OpenCL APIs. The
64 * OpenCL Runtime provides the thread on the device processor which is
65 * used to execute the kernel functions. There may be multiple device
66 * processors in a system but only one host processor.
67 *
68 * The application and the kernel functions have access to the framework
69 * components. For example, they can make calls into the XDC and SYS/BIOS
70 * components. The kernel functions also have access to the ECPY component.
71 *
72 * @a(OpenCL Programming Model)
73 * The application must create the following objects to setup an OpenCL
74 * execution environment: a context object, a command queue, and a program
75 * object. This is done with the following functions.
76 *
77 * @p(blist)
78 * - clGetPlatformIDs
79 * - clGetDeviceIDs
80 * - clCreateContext
81 * - clCreateCommandQueue
82 * - clCreateProgramWithBinary
83 * @p
84 * Once these objects have been created, the application creates a kernel
85 * object for each kernel function it wants to execute on the compute
86 * device. The kernel object is used to set the function argument values.
87 * The command queue is used to schedule a kernel function for execution.
88 *
89 * @p(blist)
90 * - clCreateKernel
91 * - clSetKernelArg
92 * - clEnqueueTask
93 * @p
94 * After a kernel function has been scheduled with a call to clEnqueueTask,
95 * the kernel object can be reused with new argument values to schedule
96 * the kernel function again.
97 * @p
98 * To release the resources used by OpenCL, the application must call the
99 * following functions before terminating.
100 *
101 * @p(blist)
102 * - clReleaseKernel
103 * - clReleaseProgram
104 * - clReleaseCommandQueue
105 * - clReleaseContext
106 * @p
107 *
108 * @a(OpenCL API Example Code)
109 * The following psudeo code gives an example of what an OpenCL program
110 * would look like. See the
111 * {@link ti.sdo.opencl.examples.hello Hello Example} for a working program.
112 *
113 * @p(code)
114 * #include <CL/opencl.h>
115 *
116 * cl_context context;
117 * cl_command_queue cmdQue;
118 * cl_program program;
119 * cl_kernel helloKnl;
120 * Ptr bufBase;
121 *
122 *
123 * // -------- OpenCL Initialization --------
124 *
125 * // get the default platform
126 * clGetPlatformIDs(.., platformAry, ..);
127 *
128 * // get an accelerator device
129 * clGetDeviceIDs(platformAry, .., deviceAry, ..);
130 *
131 * // create a context for the accelerator device
132 * context = clCreateContext(.., deviceAry, ..);
133 *
134 * // create a command-queue for the accelerator device
135 * cmdQue = clCreateCommandQueue(context, deviceAry, ..);
136 *
137 * // create program object
138 * program = clCreateProgramWithBinary(context, .., deviceAry, ..);
139 *
140 *
141 * // -------- Application Execute Phase --------
142 *
143 * // create a handle to the OpenCL kernel (function)
144 * helloKnl = clCreateKernel(program, "HelloKnl", ..);
145 *
146 * // allocate buffer using host allocated memory
147 * bufBase = Memory_alloc(heap, 64, ..);
148 *
149 * // assign the kernel arguments
150 * clSetKernelArg(helloKnl, 0, sizeof(Ptr), &bufBase);
151 *
152 * // invoke the hello world kernel
153 * clEnqueueTask(cmdQue, helloKnl, ..);
154 *
155 * // read the buffer contents
156 * System_printf("%s\n", (Char *)bufBase);
157 * Memory_free(heap, bufBase, bufSize);
158 *
159 *
160 * // -------- OpenCL Finalization --------
161 *
162 * clReleaseKernel(helloKnl);
163 * clReleaseProgram(program);
164 * clReleaseCommandQueue(cmdQue);
165 * clReleaseContext(context);
166 *
167 * @a(OpenCL Kernel Example Code)
168 * The following psudeo code gives an example of what an OpenCL kernel
169 * function looks like. For the most part, it looks just like an ordinary
170 * function. However, a kernel function must have a return type of void,
171 * cannot use recursion, and does not support pointers to functions.
172 * Additional restrictions are specified in the OpenCL Spec in Section 6.8.
173 *
174 * @p(code)
175 * #include <string.h>
176 *
177 * void HelloKnl(char *buffer)
178 * {
179 * strncpy(buffer, "Hello World");
180 * }
181 *
182 * @a(OpenCL Runtime Registration)
183 * All kernel functions must be registered with the OpenCL Runtime. This
184 * is done using static initialization. The OpenCL Runtime references the
185 * following two symbols.
186 * @p(code)
187 * Int ti_sdo_opencl_ComputeDevices_numUnits
188 * ComputeDevice_Unit ti_sdo_opencl_ComputeDevices_units[]
189 * @p
190 * When building an executable, you must provide a source file which declares
191 * and statically initializes these two symbols. The following figure
192 * gives an example.
193 * @p(html)
194 * <img src="./doc-files/KernelTable.png" />
195 * @p
196 * In the figure above, there are two units, ModA.c and ModB.c. The ModA
197 * unit defines one kernel function. The second unit, ModB, defines an
198 * init and exit function and two kernel functions. In the file KernelTable.c,
199 * an array of units is declared and initialized with the contents of
200 * ModA and ModB.
201 *
202 * Here is the source code of KernelTable.c
203 * @p(code)
204 * #include <xdc/std.h>
205 * #include <ti/sdo/opencl/ComputeDevice.h>
206 *
207 * UInt ModA_func1_args[] = {
208 * ti_cl_arg_type_GlobalPtr,
209 * ti_cl_arg_type_Int,
210 * ti_cl_arg_type_Int
211 * };
212 *
213 * ComputeDevice_FxnDesc ModA_fxnTab[] = {
214 * {
215 * "ModA_func1", // fxn name
216 * (Fxn)ModA_func1, // fxn address
217 * 3, // num args
218 * ModA_func1_args // arg types
219 * }
220 * };
221 *
222 * UInt ModB_func1_args[] = {
223 * ti_cl_arg_type_Int,
224 * ti_cl_arg_type_Int
225 * };
226 *
227 * UInt ModB_func2_args[] = {
228 * ti_cl_arg_type_Int,
229 * ti_cl_arg_type_Int,
230 * ti_cl_arg_type_Int,
231 * ti_cl_arg_type_Int
232 * };
233 *
234 * ComputeDevice_FxnDesc ModB_fxnTab[] = {
235 * {
236 * "ModB_func1", // fxn name
237 * (Fxn)ModB_func1, // fxn address
238 * 2, // num args
239 * ModB_func1_args // arg types
240 * },
241 * {
242 * "ModB_func2", // fxn name
243 * (Fxn)ModB_func2, // fxn address
244 * 4, // num args
245 * ModB_func2_args // arg types
246 * }
247 * };
248 *
249 * Int ti_sdo_opencl_ComputeDevice_numUnits = 2;
250 * ComputeDevice_Unit ti_sdo_opencl_ComputeDevice_units[] = {
251 * { // ModA
252 * NULL,
253 * NULL,
254 * 1,
255 * ModA_fxnTab
256 * },
257 * { // ModB
258 * ModB_initFxn,
259 * ModB_exitFxn,
260 * 2,
261 * ModB_fxnTab
262 * }
263 * };
264 *
265 * @a(Available Functions)
266 * The following list of OpenCL APIs are functional in this port. Please
267 * note, this is work in progress and not all features may be currently
268 * implemented.
269 *
270 * OpenCL Platform Layer
271 * @p(blist)
272 * - clGetPlatformIDs
273 * - clGetPlatformInfo
274 * - clGetDeviceIDs
275 * - clGetDeviceInfo
276 * - clCreateContext
277 * - clCreateContextFromType
278 * - clRetainContext
279 * - clReleaseContext
280 * - clGetContextInfo
281 * @p
282 *
283 * OpenCL Execution Layer
284 * @p(blist)
285 * - clCreateCommandQueue
286 * - clRetainCommandQueue
287 * - clReleaseCommandQueue
288 * - clGetCommandQueueInfo
289 * - clSetCommandQueueProperty
290 * - clCreateProgramWithBinary
291 * - clRetainProgram
292 * - clReleaseProgram
293 * - clGetProgramInfo
294 * - clCreateKernel
295 * - clSetKernelArg
296 * - clRetainKernel
297 * - clReleaseKernel
298 * @p
299 *
300 * @a(Legend)
301 * This legend applies to all figures.
302 * @p(html)
303 * <img src="./doc-files/Legend.png" />
304 * @p
305 *
306 * @a(See Also)
307 * @p(dlist)
308 * - {@link http://www.khronos.org/registry/cl/ Khronos OpenCL Web Site}
309 * - {@link ti.sdo.opencl.examples Suite of OpenCL examples for TI devices}
310 * - {@link ti.sdo.opencl.examples.hello Hellow World example}
311 * @p
312 */
313 package ti.sdo.opencl [1,0,0] {
314 module OpenCL;
315 module ComputeDevice;
316 }
317 318 319 320
321