#***********************************************************************
#
# Licensed Materials - Property of IBM
#
# (C) Copyright IBM Corp. 2009, 2011
# All Rights Reserved
#
# US Government Users Restricted Rights - Use, duplication or
# disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
#
#***********************************************************************

Name: OpenCL Build Program utility

Description:

       This utility will build a kernel binary from a user specified source, using the
       OpenCL APIs. There are two versions of this utility. 

       (1) opencl_build_program    - builds 32-bit addressing kernel binaries
       (2) opencl_build_program_64 - builds 64-bit addressing kernel binaries

       A binary versions of this utility are shipped in the OpenCL runtime
       rpms, and installed in as /usr/bin/opencl_build_program and 
       /usr/bin/opencl_build_program_64

       The utility will read in the source file (either from a filename or from
       stdin), get the list of Device IDs that match the request (default is 
       CL_DEVICE_TYPE_DEFAULT), create an OpenCL Context for that device, create an
       OpenCL Program from the source specified, call to build the program for the
       devices, get the built binary data and save it to a file.

Prerequisites:

       None

How to build:

       Copy the utility to your home directory (or another writable location):

           cp -R /usr/share/doc/OpenCL-###-ibm/utilities ~
  
         where "###" is replaced by the OpenCL SDK version number. 

       Change to that directory and make:

           cd ~/utilities

           make
            OR
           make -f Makefile_64

Running the utility:

       To display usage message:
         ./opencl_build_program --help

Command-line syntax:
 
       Usage: ./opencl_build_program [DEVICE] [OPTIONS...] [FILE]

       Build OpenCL kernel binary for specified device type from the specified FILE.
       With no FILE, or when FILE is -, source will be read from stdard input.

        Device Types: (only specify one)

         -a, --accel              build for CL_DEVICE_TYPE_ACCELERATOR
         -c, --cpu                build for CL_DEVICE_TYPE_CPU
         -A, --all                build for CL_DEVICE_TYPE_ALL
         -d, --default            build for CL_DEVICE_TYPE_DEFAULT (default)

        Options:

         -f, --flags "options"    OpenCL Buld option flags (default: none)
         -o, --output <filebase>  output binary filebase (default output <source_name>_<DEVICE NAME>.ocl
         -q, --quiet              no output (default: not quiet)
         -h, --help               display usage information and exit

Examples:

   Example 1
   ---------
       $ cat kernel.cl
       __kernel void function(__global int *a)
       {
         int gid = get_global_id(0);
         a[gid] = 1;
       }
       $ ./opencl_build_program --cpu kernel.cl
       Binary built from source file "kernel.cl" for device "CPU Cell Broadband Engine, altivec supported" saved as file "kernel_CPU_Cell_Broadband_Engine,_altivec_supported.ocl"
       $

       $ ./opencl_build_program -Aq kernel.cl
       $

   Example 2
   ---------
       $ cat k2.cl
       #include "functions.h"
       __kernel void function(__global int *a)
       {
         int gid = get_global_id(0);
         a[gid] = 1;
       }
       $ ./opencl_build_program --all --output todays_code --flags "-I." < k2.cl
       Binary built from stdin for device "ACCELERATOR PowerXCell8i processor" with options "-I." saved as file
       "todays_code_ACCELERATOR_PowerXCell8i_processor.ocl"
       Binary built from stdin for device "CPU Cell Broadband Engine, altivec supported" with options "-I." saved 
       as file "todays_code_CPU_Cell_Broadband_Engine,_altivec_supported.ocl"
       $
