Bitcode/README_HalideCodegen

Intro to Halide codegeneration pattern (based on Halide documentation)
===========================================================================

functionName:
============
Functions generated by Halide are regular functions with a user chosen name and arguments.
These functions are considered to be the public methods called by external programs.
The body checks the correctness of its arguments, then calls the function
that contains the actual computation. This function is called "__functionName".

__functionName:
=============
Actual function as defined by the Halide programmer.
These are considered to be private functions, called through the above public function.

functionName_argv:
=================
If the function is externally visible, Halide also creates an argv wrapper.
This is useful for calling from JIT and other machine interfaces.
The wrapper calls the function with an array of pointer arguments.
This is easier for the JIT to call than a function with an unknown
(at compile time) argument list.

E.g. The unit tests "simd_ops" contain functions called "test_op" and "scalar_test_op"


HOW TO: Halide bitcode generation and creating of tests and benchmarks
=======================================================================

The Halide tests in test-suite/Bitcode were generated using Halide ToT at:
https://github.com/halide/Halide

Creating a test or an application from bitcode generated code requires these stages:
1. Define a Halide pipeline
2. Generate a bitcode file with the Halide pipeline as a method, along with a header for the method prototype.
3. Create a C driver that calls the method generated, times it, compares against reference etc.
4. Link the C driver, bitcode file and Halide runtime (an already generated bitcode file found in test-suite/Bitcode)
into an executable.

1. To create a Halide pipeline/application, please visit the Halide tutorial:
http://halide-lang.org/tutorials/tutorial_introduction.html
The tests and benchmarks in test-suite/Bitcode were generated from:
https://github.com/halide/Halide/blob/master/test/correctness/simd_op_check.cpp
and
https://github.com/halide/Halide/tree/master/apps

2. Each Halide function (Func) and pipeline (Pipeline) have the following methods:
compile_to_file: generates a header and object files
compile_to_header: generates just a header file
compile_to_object: generates just an object file
compile_to_bitcode: generates a bitcode file
compile_to_llvm_assembly: generates a disassembled bitcode file (.ll)
These method provide the interface to chose a function name and file name for the Func/Pipeline.
An example from the Halide correctness tests:
https://github.com/halide/Halide/blob/master/test/correctness/simd_op_check.cpp#L166

3. The methods in the bitcode files generated for the test at 2. are invoked by the following driver:
https://github.com/halide/Halide/blob/master/apps/simd_op_check/driver.cpp

4. Typical build command for a Halide application:
clang++ test.bc driver.cpp halide_runtime.bc -lpthread -ldl