Restoring doxygen files (#3221)

[ROCm/hip commit: 02b84f231d]

projects/hip/docs/doxygen-input/mainpage.txt

@@ -0,0 +1,19 @@
+/**
+ * @file mainpage.cpp
+ * @brief : DoxyGen Main Page.
+ * @mainpage Heterogeneous-computing Interface for Portability (HIP)
+ * @tableofcontents
+ *
+ * The HIP interface makes it very easy to port existing CUDA apps to run on AMD GPUs,
+ * or to develop new apps that can run on either CUDA or AMD GPUs from a common source base.
+ *
+ *  - HIP is very thin and has little or no performance impact over coding directly in CUDA NVCC mode.
+ *  - HIP allows developers to use the "best" development environment and tools on each target platform.
+ *  - HIP allows coding in a single-source C++ programming language including features such as templates, C++11 lambdas,and more.
+ *  - HIPIFY tools automatically convert CUDA sources to HIP.
+ *  - Developers can specialize for CUDA or HIP to tune for performance or handle tricky cases with #ifdef.
+
+ *  - See the @ref API.
+
+
+*/

projects/hip/docs/doxygen-input/sync.txt

@@ -0,0 +1,49 @@
+/** @page Synchonization
+ * @tableofcontents
+
+ * # Host-synchronous behavior:
+   The following commands are "host-asynchronous" - meaning they do not wait for any preceding commands to complete, and may return control to the host thread before the requested operation completes:
+
+    - Kernel launches (hipLaunchKernel() )
+    - Asynchronous memory copies - any memory copy API which contains "Async", such as hipMemcpyAsync())
+    - Any memory set (for example, hipMemset());
+    - TODO
+
+   "Host-synchronous" commands have the following properties:
+    - wait for all previous commands to complete.
+    - will not return control back to host until the command completes.
+
+
+   The following commands are "host-synchronous". 
+
+    - hipMemcpy waits for preceding work in the same stream to complete.
+
+
+ * # Stream synchronization
+
+
+### Blocking
+
+The term "blocking" has two meanings in HIP.
+
+The first refers to synchronization commands (ie hipStreamSynchronize, hipEventSynchronize) that cause the host CPU to wait for GPU activity to complete.  
+These can either use an active where the host CPU spin-waits on the synchronization variable, or can use an interrupt-based scheme where the core is interrupted 
+when the wait completes.  The second technique is referred to as "blocking" (ie hipDeviceBlockingSync, hipEventBlockingSync) while the first is referred 
+to as "active".  Active can be appropriate for short tasks where latency is critical, but comes at the expense of a CPU core dedicated to monitoring the event.
+
+ ### HIP_LAUNCH_BLOCKING (also can use CUDA_LAUNCH_BLOCKING)
+
+    - The following commands become host-synchronous and will not return until the requested command has completed:
+
+      - Kernel launches (hipKernelLaunch).
+      - Memory set commands (hipMemset, hipMemsetAsync).
+      - Memory copy commands (hipMemcpy, hipMemsetAsync).
+
+    Note CUDA_LAUNCH_BLOCKING does add any pre-serialization to the commands and does not affect the concurrent stream behavior.  For example, 
+    even when CUDA_LAUNCH_BLOCKING is set, kernels or data copy commands launched to separate streams can execute concurrently.   Use the NULL
+    stream if additional stream synchronization is desired.
+
+
+
+ 
+*/