From 25d1a25b055ba437e9dfe4719c13243607eccd64 Mon Sep 17 00:00:00 2001
From: Sherry Yuan <sherry.yuan@intel.com>
Date: Mon, 11 Apr 2022 10:47:48 -0700
Subject: [PATCH] High level documentation for OpenCL Implementations

This documents what is fpga runtime for opencl, why it is important.
It serves the purpose of landing page to navigate to other detailed
pages that documents implementation details and contribution details.

It also links to other documentations, khronos opencl 1.2 spec as well as the intel FPGA runtime user manual.
---
 docs/README.md | 71 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 71 insertions(+)
 create mode 100644 docs/README.md

diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 00000000..77f62863
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,71 @@
+# FPGA Runtime for OpenCL documentation
+
+## OpenCL background
+
+[Khronos® OpenCL™] is a standard for writing programs that run across
+heterogeneous platforms consisting of FPGA, CPU, GPU, DSP, etc. The [Intel® FPGA
+Runtime for OpenCL™ Software Technology] implements the [OpenCL 1.2] standard
+including selected vendor extensions.
+
+## What is the FPGA runtime?
+
+The following components work together to program an [Intel® FPGA]:
+
+1. host program and host compiler
+2. OpenCL kernel(s) and offline compiler
+3. [Custom Platform]
+
+The runtime is responsible for executing the host program (1) and queueing the
+kernel to be executed on the FPGA device. It takes in the hardware programming
+image from the compiler (2), builds the contained programs, allocates
+host/shared/device memory, programs devices, enqueues and executes the kernels,
+and collects kernel execution status signaled from the memory-mapped device
+([MMD](../include/MMD/aocl_mmd.h)). Each step is described in the following.
+
+## Why is the FPGA runtime needed?
+
+FPGA hardware design deals with I/O constraints, protocols, monitoring, DDR
+calibration, and memory dependencies. The FPGA runtime provides a layer of
+abstraction to ease the development flow.
+
+### Memory
+
+Each kernel execution may require accessing device memory. The device memory
+needs to be reserved/allocated before kernel execution. The runtime keeps track
+of the memory allocation. There are two main types of memory allocations:
+[buffers](buffers.md) and unified shared memory (USM).
+
+### Kernels
+
+Kernels are data-parallel functions that extend C99 for parallelism and memory
+hierarchy.
+
+### Queues
+
+Queues manage buffer mapping, memory migration, device programming, and kernel
+execution. A queue receives asynchronous command completion notifications from
+the device. A queue also manages dependencies between commands using events and
+barriers.
+
+### Profiling
+
+The runtime keeps track of the status of a kernel execution to record the
+wall time of each stage. This provides the user with insights into the
+performance of their program.
+
+## User flow
+
+For more information on how users interact with each of the above components,
+see the [Intel® FPGA SDK for OpenCL™ Pro Edition: Programming Guide].
+
+## How to contribute
+
+To contribute to the runtime, see [CONTRIBUTING.md](../CONTRIBUTING.md).
+To build, test, and use the runtime, see [README.md](../README.md).
+
+[Khronos® OpenCL™]: https://www.khronos.org/opencl/
+[OpenCL 1.2]: https://www.khronos.org/registry/OpenCL/sdk/1.2/docs/man/xhtml/
+[Intel® FPGA]: https://www.intel.com/content/www/us/en/products/programmable.html
+[Intel® FPGA Runtime for OpenCL™ Software Technology]: https://github.com/intel/fpga-runtime-for-opencl
+[Intel® FPGA SDK for OpenCL™ Pro Edition: Programming Guide]: https://www.intel.com/content/www/us/en/docs/programmable/683846/
+[Custom Platform]: https://www.intel.com/content/www/us/en/docs/programmable/683085/