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 * ======== ti.sdo.opencl.examples.hello ========
43 * OpenCL Hello World Example
44 *
45 * This example is another spin on the classic hello world example. The
46 * application allocates a buffer and passes the buffer's base address
47 * to a kernel running on the compute device. The kernel function writes
48 * the string "Hello World" into the buffer. The application then reads
49 * the string from the buffer.
50 *
51 * @a(Example Details)
52 * The example components are illustrated in the following figure.
53 *
54 * @p(html)
55 * <br>
56 * <img src="./doc-files/Hello.png" />
57 * <br>
58 * @p
59 * The example execution steps are as follows.
60 * @p(nlist)
61 * - A kernel object is created using the kernel function name. A buffer
62 * is allocated from external memory.
63 * - The buffer's base address is set as the only argument to the kernel
64 * function. The kernel is scheduled for execution on the device processor.
65 * The host thread will block until the kernel function completes.
66 * - The OpenCL API on the host sends a message with the kernel arguments
67 * to the OpenCL Runtime on the device processor.
68 * - The OpenCL Runtime receives the message, unmarshalls the arguments,
69 * and invokes the kernel function.
70 * - The HelloKnl function writes the message into the buffer. It then
71 * returns to the OpenCL Runtime.
72 * - The OpenCL Runtime returns the message to the host processor.
73 * - The OpenCL API returns to the application.
74 * - The application reads the buffer results.
75 *
76 * @p
77 * This legend applies to all figures.
78 * @p(html)
79 * <br>
80 * <img src="./doc-files/Legend.png" />
81 * <br>
82
83 * @a(Software Dependencies)
84 * The following sofware products are required to build an OpenCL application.
85 * @p(blist)
86 * - Framework Components 3.21.00.11 lite
87 * - IPC 1.22.03.23
88 * - SYS/BIOS 6.31.03.25
89 * - XDCtools 3.20.07.86
90 * - CCS 4.2.0.10017
91 * - EVE Simulator 0.4.0.4 (T16 Compiler 1.0.0A11020 included)
92 * @p
93 * Download these products using the following links.
94 *
95 * @p(dlist)
96 * - CCS Download
97 * {@link https://processors.wiki.ti.com/index.php/Download_CCS}
98 * - Framework Components, SYS/BIOS, IPC, XDCtools
99 * {@link https://software-dl.ti.com/dsps/dsps_public_sw/sdo_sb/targetcontent/index.html}
100 * - EVE Simulator
101 * {@link http://www.india.ti.com/~isds/sim_web/products/SIM.PROD.EVE.CCSV4/installer/}
102 * @p
103 *
104 * @a(Integration Guide)
105 *
106 * This guide will help you integrate SYS/BIOS and OpenCL into your
107 * CCS projects. We will use the OpenCL Hello example as a template.
108 * Locate this project in the following folder:
109 *
110 * @p(code)
111 * Framework Component Install Folder/examples/ti/sdo/opencl/examples/hello
112 * @p
113 *
114 * There are three high level steps.
115 *
116 * @p(nlist)
117 * - Create a platform project
118 * - Integrate the OpenCL Runtime into your compute project
119 * - Integrate the OpenCL API into your host project
120 * @p
121 *
122 * @a(Create Platform Project)
123 * The platform project is setup as a CCS Standard Make project. It will
124 * build the platform specific support needed by your OpenCL executables
125 * for both the host and the compute device.
126 *
127 * @p
128 * Create a standard make project in CCS for your platform.
129 *
130 * @p(blist)
131 * - File > New > Standard Make Project
132 * - Project Name > systemcfg_ti_platforms_simArctic
133 * @p
134 *
135 * Copy all files from `hello/systemcfg/ti_platforms_simArctic` into your
136 * new project.
137 *
138 * @p(blist)
139 * - Ensure your platform project is active
140 * - Project > Add Files to Active Project
141 * - Browse to hello/systemcfg/ti_platforms_simArctic
142 * - Select all the source files
143 * @p
144 *
145 * Here is a brief description of each file.
146 *
147 * @p(dlist)
148 * - SystemCfg.h
149 * Contains system wide constants. Declares the SystemCfg API.
150 * - SystemCfg_host_bios.c
151 * The host implementation of SystemCfg. All runtime configuration is
152 * done in this file.
153 * - SystemCfg.c
154 * The device implementation of SystemCfg.
155 * - App.cfg
156 * The configuration script for the OpenCL API (host) executable.
157 * - ComputeDevice.cfg
158 * The configuration script for the OpenCL Runtime (device) executable.
159 * - config.bld
160 * Defines the memory map used by both the host and compute device
161 * executables.
162 * - makefile
163 * The makefile for this project.
164 * @p
165 *
166 * Modify the project make command to use the GNU Make executable provided
167 * by the XDCtools product.
168 *
169 * @p(blist)
170 * - Select the project in the project list
171 * - Project > Properties
172 * - Select C/C++ Make Project
173 * - Select the Make Builder tab
174 * - Build command > Use default > Unselect
175 * - Build command: ${XDCROOT}/gmake
176 * - Click Apply
177 * @p
178 *
179 * Add the `eclipse_home` variable to the build environment. The makefile
180 * references this variable to compute the CCS install folder. This
181 * ensures that when upgrading to a new CCS release, the makefile will
182 * reference the products installed into the new release.
183 *
184 * @p(blist)
185 * - Select the Environment tab
186 * - Click New
187 * @p(code)
188 * Variable: ECLIPSE_HOME
189 * Value: Click the Variables button, select eclipse_home
190 * @p
191 *
192 * Optional: you may also add the `DEPOT` variable if you have installed
193 * some products in a different location.
194 *
195 * @p(code)
196 * DEPOT = C:/CCS/Depot
197 * @p
198 *
199 * Optional: you may also add the following variables if you have installed
200 * the Code Gen Tools in a different location or need to use a specific
201 * version.
202 *
203 * @p(code)
204 * CGT_C6X_INSTALL_DIR = C:/CCS/Depot/ti_cgt_c6000_7_2_0B2
205 * CGT_T16_INSTALL_DIR = C:/CCS/Depot/ti_cgt_t16_1_0_0A11020
206 * @p
207 *
208 * Click OK in the project properties dialog.
209 *
210 * Edit the project makefile to update the product variables. They are at
211 * the top of the makefile. You need to replace the text `your_version_number`
212 * with the actual product version which is installed. For example, the
213 * XDCtools variable might look like this.
214 *
215 * @p(code)
216 * XDC_INSTALL_DIR = $(CCS_DIR)/xdctools_3_20_07_86
217 * @p
218 *
219 * To modify the memory map, edit the `config.bld` file. Note: the first
220 * time you edit this file, you must associate the XDCscript editor with
221 * this file. Do this for both `*.bld` and `*.cfg` files. Subsequently,
222 * you will be able to just double-click the file to edit it.
223 *
224 * @p(blist)
225 * - Select config.bld
226 * - Right-Mouse-Button > Open With > XDCscript Editor
227 * @p
228 *
229 * The variable `MemMapSects` defines all the memory map sections and
230 * their properties. You can modify, add, or remove these as needed for
231 * your executable. Use the comment at the top of the file to help keep
232 * track of your memory map. See the xdc.platform.IPlatform documentation
233 * for a description of the memory map section. Each memory map section is
234 * of type `metaonly struct Memory` defined in the documentation.
235 *
236 * Edit your linker command files from your host and device projects. Look
237 * for the `MEMORY` directive. Using the memory sections defined in your
238 * linker command file, create similar sections in the MemMapSects object.
239 * Delete any unused sections.
240 *
241 * Here is the memory directive from the device (T16) project.
242 * @p(code)
243 * MEMORY
244 * {
245 * VECS (RW) : org = 0x00000000, len = 0x001000
246 * DMEM (RW) : org = 0x10020000, len = 0x007C00
247 * PMEM (RW) : org = 0x10027C00, len = 0x000400
248 * CODE (RWX) : org = 0x81000000, len = 0x100000
249 * }
250 * @p
251 *
252 * Here is the memory directive from the host (DSP) project.
253 * @p(code)
254 * MEMORY
255 * {
256 * PMEM (RW) : org = 0x20027C00, len = 0x000400
257 * CODE (RWX) : org = 0x80000000, len = 0x100000
258 * DATA (RWX) : org = 0x80100000, len = 0x100000
259 * }
260 * @p
261 *
262 * Here is the MemMapSects object which combines the memory sections
263 * from both linker command files.
264 * @p(code)
265 * // Memory Map
266 * // 0000_0000 - 0000_0FFF 1000 ( 4 KB) VECS
267 * // 1002_0000 - 1002_6FFF 7000 ( 28 KB) DMEM (data)
268 * // 1002_7000 - 1002_7FFF 1000 ( 4 KB) IPC_SR0_T16 (SharedRegion_0)
269 * // 2002_7000 - 2002_7FFF 1000 ( 4 KB) IPC_SR0_DSP (SharedRegion_0)
270 * // 8000_0000 - 800F_FFFF 10_0000 ( 1 MB) CODE_DSP
271 * // 8010_0000 - 801F_FFFF 10_0000 ( 1 MB) DATA_DSP
272 * // 8100_0000 - 810F_FFFF 10_0000 ( 1 MB) CODE_T16
273 * // 8110_0000 - 811F_FFFF 10_0000 ( 1 MB) DATA_T16
274 * // 8200_0000 - 8FFF_FFFF E00_0000 ( 224 MB) --------
275 *
276 * var MemMapSects = {
277 * VECS: {
278 * name: "VECS", space: "data/code", access: "RW",
279 * base: 0, len: 0x1000,
280 * comment: "Vector Table (4 KB)"
281 * },
282 * DMEM: {
283 * name: "DMEM", space: "data", access: "RW",
284 * base: 0x10020000, len: 0x7000,
285 * comment: "Local data memory (28 KB)"
286 * },
287 * IPC_SR0_T16: {
288 * name: "IPC_SR0_T16", space: "data", access: "RW",
289 * base: 0x10027000, len: 0x1000,
290 * comment: "IPC SharedRegion_0 T16 (4 KB)"
291 * },
292 * IPC_SR0_DSP: {
293 * name: "IPC_SR0_DSP", space: "data", access: "RW",
294 * base: 0x20027000, len: 0x1000,
295 * comment: "IPC SharedRegion_0 DSP (4 KB)"
296 * },
297 * CODE_DSP: {
298 * name: "CODE_DSP", space: "code/data", access: "RWX",
299 * base: 0x80000000, len: 0x100000,
300 * comment: "DSP Code Memory (1 MB)"
301 * },
302 * DATA_DSP: {
303 * name: "DATA_DSP", space: "data", access: "RW",
304 * base: 0x80100000, len: 0x100000,
305 * comment: "DSP Data Memory (1 MB)"
306 * },
307 * CODE_T16: {
308 * name: "CODE_T16", space: "code/data", access: "RWX",
309 * base: 0x81000000, len: 0x100000,
310 * comment: "T16 Code Memory (1 MB)"
311 * },
312 * DATA_T16: {
313 * name: "DATA_T16", space: "data", access: "RW",
314 * base: 0x81100000, len: 0x100000,
315 * comment: "T16 Data Memory (1 MB)"
316 * }
317 * };
318 * @p
319 *
320 * Note that program code and data sections have names to reflect which
321 * core they apply to (e.g. CODE_DSP, CODE_T16). The DMEM section is slightly
322 * smaller to accomodate the SharedRegion_0 section. The SharedRegion_0
323 * memory section replaces the KARG memory section. It is used by the OpenCL
324 * implementation for passing kernel function arguments. The VECS section
325 * is required by SYS/BIOS.
326 *
327 * At the bottom of the config.bld file, are two platform instances. Each
328 * instance is defined as an entry to the `Build.platformTable` object.
329 * Each instance defines its memory map and section placement. Edit these
330 * as needed for your executable. See the xdc.bld.BuildEnvironment
331 * documentation for a description of the platformTable object.
332 *
333 * Here are the platform instances using the memory map defined above. Note
334 * that each platform instance only uses the memory sections it needs.
335 * @p(code)
336 * Build.platformTable["ti.platforms.simArctic:t16"] = {
337 * customMemoryMap: [
338 * [ "VECS", MemMapSects.VECS ],
339 * [ "DMEM", MemMapSects.DMEM ],
340 * [ "IPC_SR0_T16", MemMapSects.IPC_SR0_T16 ],
341 * [ "CODE_T16", MemMapSects.CODE_T16 ],
342 * [ "DATA_T16", MemMapSects.DATA_T16 ]
343 * ],
344 * codeMemory: "CODE_T16",
345 * dataMemory: "DATA_T16",
346 * stackMemory: "DATA_T16"
347 * };
348 *
349 * Build.platformTable["ti.platforms.simArctic:dsp"] = {
350 * customMemoryMap: [
351 * [ "IPC_SR0_DSP", MemMapSects.IPC_SR0_DSP ],
352 * [ "CODE_DSP", MemMapSects.CODE_DSP ],
353 * [ "DATA_DSP", MemMapSects.DATA_DSP ]
354 * ],
355 * l1DMode: "0k",
356 * l1PMode: "0k",
357 * l2Mode: "0k",
358 * codeMemory: "CODE_DSP",
359 * dataMemory: "DATA_DSP",
360 * stackMemory: "DATA_DSP"
361 * };
362 * @p
363 *
364 * If you defined the heap size in your original linker command file, then
365 * you need to define the heap size in the executable configuration script.
366 * For example, the device linker command file for the device project defined
367 * the heap size as follows.
368 * @p(code)
369 * -heap 0x2000
370 * @p
371 *
372 * Edit the ComputeDevice.cfg script and set the program heap size as follows:
373 * @p(code)
374 * Program.heap = 0x2000;
375 * @p
376 *
377 * Do the same thing for defining the boot thread stack size. Here is the
378 * linker command file stack definition.
379 * @p(code)
380 * -stack 0x1000
381 * @p
382 *
383 * Here is the equivalent config script definition.
384 * @p(code)
385 * Program.stack = 0x1000;
386 * @p
387 *
388 * If there are any custom section placement directives in the linker
389 * command file, these will also need to be defined in the executable
390 * config script. For example, consider the following section placement
391 * in the linker command file.
392 * @p(code)
393 * SECTIONS
394 * {
395 * .mySect: load > DATA
396 * }
397 * @p
398 *
399 * The executable config script would look as follows.
400 * @p(code)
401 * Program.sectMap[".mySect"] = new Program.SectionSpec();
402 * Program.sectMap[".mySect"].loadSegment = "DATA";
403 * @p
404 *
405 * To summarize, the memory map is shared between both executables and
406 * is defined in `config.bld`. In the same file, we define a platform
407 * instance for each executable. Custom linker directives are specified
408 * for each executable in its config script.
409 *
410 * Once you have integrated the memory map and linker command file
411 * directives into the platform project, you are now ready to build it.
412 * The CCS build command will use the makefile in the project which builds
413 * the platform support for both the host and device executables.
414 *
415 * @p(blist)
416 * - Project > Build Active Project
417 * @p
418 *
419 * When the build finishes, you should have the following files in your
420 * project.
421 *
422 * @p(dlist)
423 * - lib/debug/App_systemcfg.ae674
424 * The system configuration library for your host executable.
425 * - configuro_App/linker.cmd
426 * The linker command file for your host executable.
427 * - lib/debug/ComputeDevice_systemcfg.aet16
428 * The system configuration library for your device executable.
429 * - configuro_ComputeDevice/linker.cmd
430 * The linker command file for your device executable.
431 * @p
432 *
433 * @a(Integrate the OpenCL Runtime)
434 * To integrate the OpenCL Runtime, you will need to either replace your
435 * main() function with the one provided or integrate the same calls into
436 * your existing main(). This example will replace the existing main(). It
437 * also assumes your device project is a CCS Standard Make project.
438 *
439 * Set your device project as your active project.
440 *
441 * @p(blist)
442 * - Select your device project in the project browser
443 * - Right-Mouse-Button > Set as Active Project
444 * @p
445 *
446 * Add the `eclipse_home` and `workspace_loc` variables to the build
447 * environment.
448 *
449 * @p(blist)
450 * - Select the project in the project list
451 * - Project > Properties
452 * - Select C/C++ Make Project
453 * - Select the Environment tab
454 * - Click New to add the `eclipse_home` variable
455 * @p(code)
456 * Variable: ECLIPSE_HOME
457 * Value: Click the Variables button, select eclipse_home
458 * @p(blist)
459 * - Click New to add the `workspace_loc` variable
460 * @p(code)
461 * Variable: WORKSPACE_DIR
462 * Value: Click the Variables button, select workspace_loc
463 * @p
464 *
465 * Optional: you may also add the `DEPOT` variable if you have installed
466 * some products in a different location.
467 *
468 * @p(code)
469 * DEPOT = C:/CCS/Depot
470 * @p
471 *
472 * Optional: you may also add the following variables if you have installed
473 * the Code Gen Tools in a different location or need to use a specific
474 * version.
475 *
476 * @p(code)
477 * CGT_T16_INSTALL_DIR = C:/CCS/Depot/ti_cgt_t16_1_0_0A11020
478 * @p
479 *
480 * Click OK in the project properties dialog.
481 *
482 * Edit the source file which contains your main() function. You can either
483 * rename it or comment it out.
484 *
485 * @p(blist)
486 * - Edit main.c
487 * - Comment out or rename main()
488 * @p
489 *
490 * Copy `main_server_bios.c` and `KernelTable.c` from the OpenCL Hello
491 * Example into your project.
492 *
493 * @p(blist)
494 * - Ensure your platform project is active
495 * - Project > Add Files to Active Project
496 * - Browse to ti/sdo/opencl/examples/hello
497 * - Select the following files
498 * @p(code)
499 * main_server_bios.c
500 * KernelTable.c
501 * @p(blist)
502 * - Click Open
503 * @p
504 *
505 * Edit the makefile in your project. Make the following changes. You can
506 * use the OpenCL Hello Example's makefile as a template.
507 *
508 * @p(blist)
509 * - Add the source files main_server_bios.c and KernelTable.c to list
510 * of source files.
511 * @p(code)
512 * ComputeDevice_srcs = main_server_bios.c HelloKnl.c KernelTable.c
513 * ComputeDevice_objs = \
514 * $(addprefix bin/$(PLAT)/$(PROFILE)/, \
515 * $(patsubst %.c,%.o$(SUFFIX),$(ComputeDevice_srcs)))
516 * @p(blist)
517 * - Add the CCS_DIR and product variables. Be sure to update the product
518 * version number. Replace `CCS_DIR` with `DEPOT` if your products are
519 * installed in a different location.
520 * @p(code)
521 * CCS_DIR = "$(subst /C:,C:,$(subst /ccsv4/eclipse/,,$(ECLIPSE_HOME)))"
522 *
523 * FC_INSTALL_DIR = $(CCS_DIR)/framework_components_your_version_number
524 * IPC_INSTALL_DIR = $(CCS_DIR)/ipc_your_version_number
525 * BIOS_INSTALL_DIR = $(CCS_DIR)/bios_your_version_number
526 * XDC_INSTALL_DIR = $(CCS_DIR)/xdctools_your_version_number
527 * @p(blist)
528 * - Add the product repositories and your workspace to the include path.
529 * @p(code)
530 * INCPATH = $(WORKSPACE_DIR) \
531 * $(FC_INSTALL_DIR)/packages \
532 * $(FC_INSTALL_DIR)/khronos/opencl \
533 * $(IPC_INSTALL_DIR)/packages \
534 * $(BIOS_INSTALL_DIR)/packages \
535 * $(XDC_INSTALL_DIR)/packages
536 *
537 * CFLAGS = -qq -pdsw225 $(CCPROFILE_$(PROFILE)) \
538 * -I. $(addprefix -I,$(INCPATH)) -I$(CGTOOLS)/include
539 * @p(blist)
540 * - Add the following compiler defines. These are used when including
541 * the file xdc/std.h which defines the XDCtools Standard Types.
542 * @p(code)
543 * CPPFLAGS = -Dxdc_target_name__=T16 -Dxdc_target_types__=ti/targets/elf/std.h
544 * @p(blist)
545 * - Replace your `linker.cmd` file with the one provided by the platform
546 * project. Recall that the platform project builds for both executables;
547 * be sure to use the one in the `configuro_ComputeDevice` folder. Also,
548 * add the system config library for your executable.
549 * @p(code)
550 * ComputeDevice_libs = \
551 * systemcfg/$(PLAT)/lib/$(PROFILE)/ComputeDevice_systemcfg.a$(SUFFIX) \
552 * systemcfg/$(PLAT)/configuro_ComputeDevice/linker.cmd
553 * @p
554 *
555 * Edit the file `main_server_bios.c` and change the include statement for
556 * the system configuration header file. Search for the following lines:
557 * @p(code)
558 * #define SYSINC(m) <m>
559 * #include SYSINC(Platform_SystemCfg_h)
560 * @p
561 * Replace with the following, make sure to use your platform project name.
562 * @p(code)
563 * #include <systemcfg_ti_platforms_simArctic/SystemCfg.h>
564 * @p
565 *
566 * Edit the source file which declares your device functions which are to
567 * be invoked as OpenCL Runtime kernels. You will need to create a function
568 * table of type `ComputeDevice_FxnDesc[]` which will be used to register
569 * your functions with the OpenCL Runtime. Make the following changes. You
570 * can use the OpenCL Hello Example's `HelloKnl.c` files as a template.
571 *
572 * @p(blist)
573 * - Include the following header files.
574 * @p(code)
575 * #include <xdc/std.h>
576 * #include <ti/sdo/opencl/ComputeDevice.h>
577 * @p(blist)
578 * - Define an array of argument types for each of your functions. Do this
579 * at the end of your source file. Here is a typical example.
580 * @p(code)
581 * UInt HelloKnl_funcA_args[] = {
582 * ti_cl_arg_type_GlobalPtr,
583 * ti_cl_arg_type_Int,
584 * ti_cl_arg_type_Int
585 * };
586 * @p(blist)
587 * - Define the unit's function table. Each unit has one function table
588 * which defines each funtion in that unit which needs to be registered
589 * with the OpenCL Runtime. Do this at the end of your source file. This
590 * example registers only one function.
591 * @p(code)
592 * ComputeDevice_FxnDesc HelloKnl_fxnTab[] = {
593 * {
594 * "HelloKnl_funcA", // fxn name
595 * (Fxn)HelloKnl_funcA, // fxn address
596 * 3, // num args
597 * HelloKnl_funcA_args // arg types
598 * }
599 * };
600 * @p
601 *
602 * Edit the header file which declares your device functions which are to
603 * be invoked as OpenCL Runtime kernels. You will need to declare your
604 * `init()` and `exit()` functions, the number of available kernel functions,
605 * and the kernel function table. Make the following changes. You can use
606 * the OpenCL Hello Example's HelloKnl.h file as a tempalte.
607 *
608 * @p(blist)
609 * - Include the `ComputeDevice.h` header file
610 * @p(code)
611 * #include <ti/sdo/opencl/ComputeDevice.h>
612 * @p(blist)
613 * - Declare your unit's `init()` and `exit()` functions if you have them.
614 * Otherwise, simply `#define` them to `NULL`.
615 * @p(code)
616 * #define HelloKnl_initFxn NULL
617 * #define HelloKnl_exitFxn NULL
618 * @p(blist)
619 * - Declare the number of kernel functions in your function table.
620 * @p(code)
621 * #define HelloKnl_numFxns 1
622 * @p(blist)
623 * Declare the name of the kernel function table.
624 * @p(code)
625 * extern ComputeDevice_FxnDesc HelloKnl_fxnTab[];
626 * @p(blist)
627 * - Optional: remove the original function declarations. They will be
628 * invoked by the OpenCL Runtime and are no longer needed in the header
629 * file.
630 * @p
631 *
632 * Edit the file KernelTable.c. You will need to include the header file
633 * you just modified and add the kernel function table to the units array
634 * defined in this file. Make the following changes.
635 *
636 * @p(blist)
637 * - Include your header file(s) which defines your kernel functions.
638 * @p(code)
639 * #include "HelloKnl.h"
640 * @p(blist)
641 * - Add the kernel function table to the units array.
642 * @p(code)
643 * ComputeDevice_Unit ti_sdo_opencl_ComputeDevice_units[] = {
644 *
645 * { // HelloKnl
646 * HelloKnl_initFxn,
647 * HelloKnl_exitFxn,
648 * HelloKnl_numFxns,
649 * HelloKnl_fxnTab
650 * }
651 * };
652 * @p(blist)
653 * - Update the number of units to reflect how many units you have added
654 * to the array.
655 * @p(code)
656 * Int ti_sdo_opencl_ComputeDevice_numUnits = 1;
657 * @p
658 *
659 * You are now ready to build your project. Clean and build your project.
660 *
661 * @p(blist)
662 * - Select your project
663 * - Right-Mouse-Button > Clean Project
664 * - Project > Build Active Project
665 * @p
666 *
667 * When the build completes, you should have both debug and release
668 * executables in your `bin` folder.
669 * @p(code)
670 * bin/ti_platforms_simArctic/debug/ComputeDevice.xet16
671 * bin/ti_platforms_simArctic/release/ComputeDevice.xet16
672 * @p
673 *
674 * @a(Integrate the OpenCL API)
675 * To integrate the OpenCL API into your application, you will need to
676 * replace your main() function with the one provided. You will then add
677 * OpenCL API calls to create a context, program, command queue, and kernel
678 * handles. Using these handles, you will then set kernel arguments and
679 * schedule kernel functions for execution on the device core. This guide
680 * assumes the project type is a CCS C6000 native project.
681 *
682 * To begin, ensure that your host project is active.
683 *
684 * @p(blist)
685 * - Select your device project in the project browser
686 * - Right-Mouse-Button > Set as Active Project
687 * @p
688 *
689 * Optional: if you have installed SYS/BIOS, IPC, or Framework Components
690 * in a location different from the CCS install folder, then add the DEPOT
691 * variable to your project and set it to the location of your products.
692 *
693 * @p(blist)
694 * - Select the project in the project list
695 * - Project > Properties
696 * - Select C/C++ Build
697 * - Select the Macros tab
698 * - Click New
699 * @p(code)
700 * Name: DEPOT
701 * Type: String
702 * Value: C:/CCS/Depot
703 * @p
704 *
705 * Add the following compiler defines. These are used when including
706 * the file xdc/std.h which defines the XDCtools Standard Types.
707 *
708 * @p(blist)
709 * - Select the project in the project list
710 * - Project > Properties
711 * - Select C/C++ Build
712 * - Select the Tool Settings tab
713 * - Select C6000 Compiler > Predefined Symbols
714 * - Using the Add button in the Pre-defined NAME box, add the following
715 * defines.
716 * @p(code)
717 * xdc_target_name__=C674
718 * xdc_target_types__=ti/targets/elf/std.h
719 * @p
720 *
721 * Add the following directories to the compiler include path. Add these
722 * before the Code Gen Tools include folder.
723 *
724 * @p(blist)
725 * - Select C6000 Compiler > Include Options
726 * - Using the Add button, add the following include folders. If your
727 * products are installed in a different location, replace
728 * `${CCS_INSTALL_ROOT}/../` with `${DEPOT}/`.
729 * @p(code)
730 * ${CCS_INSTALL_ROOT}/../framework_components_3_21_00_11_eng/packages
731 * ${CCS_INSTALL_ROOT}/../framework_components_3_21_00_11_eng/packages/khronos/opencl
732 * ${CCS_INSTALL_ROOT}/../ipc_1_22_03_23/packages
733 * ${CCS_INSTALL_ROOT}/../bios_6_31_03_25/packages
734 * ${CCS_INSTALL_ROOT}/../xdctools_3_20_07_86/packages
735 * ${workspace_loc}
736 * @p
737 *
738 * Add the following library and the linker command file from the
739 * platform project to the linker command line. Place them before the
740 * `libc.a` library.
741 *
742 * @p(blist)
743 * - Select C6000 Linker > File Search Path
744 * - Using the Add button, add the following library and command file.
745 * @p(code)
746 * ${workspace_loc}/systemcfg_ti_platforms_simArctic/lib/release/App_systemcfg.ae674
747 * ${workspace_loc}/systemcfg_ti_platforms_simArctic/configuro_App/linker.cmd
748 * @p
749 *
750 * Remove any linker command file which might be assigned on the CCS Build
751 * properties page.
752 * @p(blist)
753 * - Select CCS Build
754 * - Select the General tab
755 * - Clear the Linker Command File textfield
756 * @p
757 *
758 * Click the OK button to apply all your changes and to dismiss the dialog.
759 *
760 * You need to rename your existing main() function to main_app() and
761 * change the function signature. There is a call to main_app() from
762 * the main_host_bios.c source file.
763 *
764 * @p(blist)
765 * - Rename `main()` to `main_app()`
766 * - `int main_app(char *progConfig)`
767 * @p
768 *
769 * Copy main_host_bios.c from the OpenCL Hello Example into your project.
770 *
771 * @p(blist)
772 * - Ensure your host project is active
773 * - Project > Add Files to Active Project
774 * - Browse to ti/sdo/opencl/examples/hello
775 * - Select the following file
776 * @p(code)
777 * main_host_bios.c
778 * @p(blist)
779 * - Click Open
780 * @p
781 *
782 * Edit the file `main_host_bios.c` and change the include statement for
783 * the system configuration header file. Search for the following lines:
784 * @p(code)
785 * #define SYSINC(m) <m>
786 * #include SYSINC(Platform_SystemCfg_h)
787 * @p
788 * Replace with the following, make sure to use your platform project name.
789 * @p(code)
790 * #include <systemcfg_ti_platforms_simArctic/SystemCfg.h>
791 * @p
792 *
793 * Edit the file which will invoke the kernel functions on the device
794 * processor. You will add the following OpenCL API function calls. You
795 * can use the OpenCL Hello Example's Hello.c file as a template.
796 *
797 * @p(blist)
798 * - Include the `OpenCL.h` header file
799 * @p(code)
800 * #include <CL/opencl.h>
801 * @p(blist)
802 * Add the following functions to create an OpenCL context, command queue,
803 * and program object. Use the `progConfig` argument passed to your
804 * main_app() when creating the program object.
805 * @p(code)
806 * cl_platform_id platformAry[1];
807 * cl_device_id deviceAry[1];
808 * cl_context context;
809 * cl_command_queue cmdQue;
810 * cl_context_properties contextPropertyAry[8];
811 * cl_program program;
812 * size_t progLenAry[1];
813 * const unsigned char * progBinAry[1];
814 *
815 * // get a platform, default platform has all available devices
816 * clGetPlatformIDs(1, platformAry, NULL);
817 *
818 * // get an accelerator device
819 * clGetDeviceIDs(platformAry[0], CL_DEVICE_TYPE_ACCELERATOR,
820 * 1, deviceAry, NULL);
821 *
822 * // create a context for the accelerator device
823 * contextPropertyAry[0] = CL_CONTEXT_PLATFORM;
824 * contextPropertyAry[1] = (cl_context_properties)platformAry[0];
825 * contextPropertyAry[2] = 0;
826 * context = clCreateContext(contextPropertyAry, 1, deviceAry,
827 * NULL, NULL, NULL);
828 *
829 * // create a command-queue for the accelerator device
830 * cmdQue = clCreateCommandQueue(context, deviceAry[0], NULL, NULL);
831 *
832 * // create program from binary, load it on the accelerator device
833 * progLenAry[0] = strlen(progConfig);
834 * progBinAry[0] = (const unsigned char *)progConfig;
835 *
836 * program = clCreateProgramWithBinary(context, 1, deviceAry,
837 * progLenAry, progBinAry, NULL, NULL);
838 * @p(blist)
839 * - Create a handle for each remote kernel you want to call. Use the
840 * kernel's string name that you used when defining the kernel function
841 * table.
842 * @p(code)
843 * cl_kernel helloKnl;
844 *
845 * // create a handle to the compiled OpenCL function (kernel)
846 * helloKnl = clCreateKernel(program, "HelloKnl_funcA", NULL);
847 * @p(blist)
848 * Add the following calls to set the kernel arguments and to schedule
849 * it for execution.
850 * @p(code)
851 * #define BUF_SIZE 64
852 *
853 * Char cbuf[BUF_SIZE];
854 * Ptr bufBase = cbuf;
855 * Int bufSize = BUF_SIZE;
856 * Int ctrl;
857 *
858 * // assign the kernel arguments
859 * clSetKernelArg(helloKnl, 0, sizeof(Ptr), (const void *)&bufBase);
860 * clSetKernelArg(helloKnl, 1, sizeof(Int), (const void *)&bufSize);
861 *
862 * ctrl = 0;
863 * clSetKernelArg(helloKnl, 2, sizeof(Int), (const void *)&ctrl);
864 *
865 * // invoke the hello world kernel
866 * clEnqueueTask(cmdQue, helloKnl, 0, NULL, NULL);
867 * @p(blist)
868 * Add the following calls to release all the resources used by OpenCL.
869 * @p(code)
870 * clReleaseKernel(helloKnl);
871 * clReleaseProgram(program);
872 * clReleaseCommandQueue(cmdQue);
873 * clReleaseContext(context);
874 * @p
875 *
876 * You are now ready to build your project. Clean and build your project.
877 *
878 * @p(blist)
879 * - Select your project
880 * - Right-Mouse-Button > Clean Project
881 * - Project > Build Active Project
882 * @p
883 *
884 * When the build completes, you should have the following file in your
885 * project.
886 *
887 * @p(dlist)
888 * - Debug/Hello.xe674
889 * The debug host executable.
890 * @p
891 */
892 package ti.sdo.opencl.examples.hello [1,0,0] {
893 }
894 895 896 897
898