add installation doc

docs/source/conf.py

@@ -194,7 +194,7 @@
 sphinx_gallery_conf = {
         'examples_dirs': ['../../samples', '../../tutorials'],
         'gallery_dirs': ['samples', 'tutorials'],
-        'ignore_pattern': '(.*data\.py)|(.*merlinc\.py)|(example.*py)|(test.*py)|(__init__.py)|(.*golden.*py)|(.*_vhls\.py)',
+        'ignore_pattern': '(.*data\.py)|(.*merlinc\.py)|(example.*py)|(test.*py)|(__init__.py)|(.*golden.*py)|(.*_vhls\.py)|(.*stream\.py)|(.*_sdaccel\.py)|(.*withoutq.*)',
         'filename_pattern': '(.*_main\.py)|(tutorial.*py)',
         'within_subsection_order': FileNameSortKey,
         'download_all_examples': False,

docs/source/heterocl.api.rst

@@ -11,6 +11,8 @@ heterocl\.api
    heterocl.lower
    heterocl.build
    heterocl.cast
+   heterocl.select
+   heterocl.print
 
 .. autofunction:: heterocl.init
 .. autofunction:: heterocl.placeholder
@@ -20,3 +22,5 @@ heterocl\.api
 .. autofunction:: heterocl.lower
 .. autofunction:: heterocl.build
 .. autofunction:: heterocl.cast
+.. autofunction:: heterocl.select
+.. autofunction:: heterocl.print

docs/source/install_from_prebuilt.rst

@@ -0,0 +1,38 @@
+Insrall from Pre-built Images
+=============================
+With this method, you can easily deploy and try out HeteroCL. However, to use the latest features and patches,
+please install from source.
+
+Install with Conda
+------------------
+First install conda (Anaconda or miniconda) and create an empty virtual environment. It is recommended to install HeteroCL in a new conda env without any other pre-installed packages to avoid potential conflicts. 
+
+.. code:: bash
+
+    conda create --name hcl-env
+    conda activate hcl-env
+
+After activating the conda environment, you can install the pre-built heterocl library and python packages.
+
+.. code:: bash
+
+    conda install -c cornell-zhang heterocl
+
+
+Install with Docker
+-------------------
+First make sure docker service is activated on your system by running the hello-world docker image example.
+
+.. code:: bash
+
+    docker run hello-world
+
+Then pull back the docker image from DockerHub, and run it using interactive mode. Conda virtual env is pre-installed in the docker image. After activating the conda env, you can use the HeteroCL package.
+
+.. code:: bash
+
+    docker pull hecmay/heterocl:0.3
+    docker run -it hecmay/heterocl:0.3 bash
+
+    source /opt/conda/etc/profile.d/conda.sh
+    conda activate py36

docs/source/install_from_src.rst

@@ -0,0 +1,38 @@
+Build and Install from Source
+=============================
+To build and install HeteroCL from source, please follow the following steps.
+
+1. Create a virtual environment with conda (e.g., Anaconda or miniconda)
+2. Download the source code from GitHub. For developers, please **fork** from the repo instead. 
+
+.. code:: bash
+
+    git clone https://github.com/cornell-zhang/heterocl.git
+
+3. (*Optional*) Specify the CMake and/or LLVM path in ``Makefile.config``. For instance
+
+.. code::
+
+    # set your own path to llvm-config
+    LLVM_CONFIG = /path/to/llvm-config
+
+4. Run `make` to build and install HeteroCL. Note that for Mac users, you need to make sure `cmake` and `wget` are installed before running this command. It is recommended to install these tools using conda with `conda install wget cmake -y`
+
+.. code:: bash
+
+    make -j8
+
+For Developers
+--------------
+
+1. Set the environment variable ``PYTHONPATH`` to reflect the modifications of Python files
+
+.. code:: bash
+
+    export PYTHONPATH=$HCL_HOME/python:$HCL_HOME/hlib/python
+
+2. Run `make` under ``tvm`` to reflect the modification of C source files
+
+.. code:: bash
+
+    make -C tvm

docs/source/installation.rst

@@ -1,21 +1,11 @@
 Installation
 ============
-To install HeteroCL, simply clone it from the GitHub.
 
-.. code:: bash
-
-    git clone --recursive https://github.com/cornell-zhang/heterocl.git
+To install HeteroCL, we provide two ways: you can either build from source or use-prebuilt images with
+conda or docker.
 
-After that, go to the downloaded directory and make it.
 
-.. code:: bash
+.. toctree::
 
-    make -j8
-
-We highly recommend running HeteroCL with Python 3 since Python 2 will be deprecated in 2020.
-
-Options
--------
-
-1. You can set your own CMake or LLVM version by setting the PATH in ``Makefile.config``.
-2. You can turn off the VHLS C simulation feature by setting ``USE_VIVADO_HLS`` to 0 in ``Makefile.config``.
+   install_from_src
+   install_from_prebuilt

tutorials/tutorial_10_platform.py

@@ -0,0 +1,89 @@
+"""
+Use HeteroCL Platform Features
+=======================
+**Author**: Shaojie Xiang
+
+In this tutorial, we show how to use the pre-defined platforms and configure the corresponding 
+toolflows in HeteroCL. The platform class contains a pre-defined list of supported platforms (e.g. 
+`hcl.platform.aws_f1` equipped with one VU9P FPGA acceleration card and an Intel Xeon CPU). HeteroCL
+allows users to add their own custom platforms with various accelerators. The platform information 
+along with data placement scheme will be used to generate target specific backend code.
+
+"""
+import numpy as np
+import heterocl as hcl
+
+##############################################################################
+# Create a program in HeteroCL
+# -------------------
+# Here we use the stencil kernel from last tutorial to showcase how to use the platform 
+# feature to generate host and device code, and run the program in different modes (e.g.
+# software simulation, co-simulation or bistream).
+
+def jacobi(input_image):
+    def jacobi_kernel(y, x):
+        return (input_image[y+1, x-1] +
+                input_image[y  , x  ] +
+                input_image[y+1, x  ] +
+                input_image[y+1, x+1] +
+                input_image[y+2, x  ]) / 5
+
+    return hcl.compute(input_image.shape, jacobi_kernel, name="output")
+
+dtype = hcl.Float()
+input_image = hcl.placeholder((480, 640), name="input", dtype=dtype)
+s = hcl.create_schedule([input_image], jacobi)
+
+##############################################################################
+# Use the pre-defined platform 
+# -----------------------
+# Here we use the AWS F1 platform for demonstration. Users can configure the 
+# the toolflow used on the platform. The supported toolflows : "vitis" (Xilinx Vitis), 
+# sdsoc(Xilinx SDSoC), "aocl" (Intel AOCL) and "vivado_hls" (Vivado HLS). 
+# HeteroCL provides users with four tool modes to facilitate the development process: 
+# sw_sim, hw_sim, hw_exe and debug. HeteroCL will return the generated code (i.e. host and device code) 
+# in the debug mode, or the compiled function in the other modes. The compiled function is hooked
+# with the hardware or software running in the background. Namely, you can invoke FPGA or other 
+# accelerators with the python compiled function returned HeteroCL. HeteroCL runtime will handle the 
+# the compilation and deployment process based on the platform information.
+
+p = hcl.platform.aws_f1
+# return host and device code in string
+p.config(compile="vitis", mode="debug")
+print(hcl.build(s, p))
+
+# return compiled function hooked up with FPGA accelerator 
+p.config(compile="vitis", mode="hw_exe", backend="vhls")
+f = hcl.build(s, p)
+
+##############################################################################
+# Create a user-defined platform  
+# --------------------
+# HeteroCL has the following built-in platforms: aws_f1, zc706, vlab, ppac, stratix10.
+# You can also add a custom platform with different sets of devices. For example, we
+# can create a custom platform with one Xeon-E5 CPU and two Alveo FPGAs.
+
+config = {
+    "host" : hcl.dev.cpu("intel", "e5"),
+    "xcel" : [
+        hcl.dev.fpga("xilinx", "xcvu19p"),
+        hcl.dev.fpga("xilinx", "xcvu19p")
+    ]
+}
+p = hcl.platform.custom(config)
+p.config(compile="vitis", mode="debug", backend="vhls")
+
+##############################################################################
+# Data Movement between Devices 
+# --------------------
+# The whole HeteroCL program is palced on host by default (as you may notice, 
+# HeteroCL returns empty device code in debug mode if no data movement is specified).
+# The .to API allows users to move data to different device, and HeteroCL will
+# figure out the portiton of the program to be mapped to accelerator. For example, 
+# the input image is moved to device scope, and the stencil kernel is executed on
+# the device before the output is moved to host.
+
+tensor = jacobi.output
+s.to(input_image, p.xcel)
+s.to(tensor, p.host)
+print(hcl.build(s, p))