Documentation refactoring [2/n]

- Update contributing guidelines
- Split and cleanup FAQ
- Cleanup README

Change-Id: Iae595fdff51e02f8ec4a3f72e4c4b45eb8d0c061
Signed-off-by: Adam Cetnerowski <adam.cetnerowski@intel.com>

Author: AdamCetnerowski

CONTRIBUTING.md

@@ -7,13 +7,17 @@
 Start with a patch (we prefer smaller self-contained incremental changes vs. large blobs of code).
 When adding new code, please also add corresponding unit level tests (ULT). Added ULTs should cover
 all the decision points introduced by the commit and should fail if executed without the code changes.
-Make sure it builds and passes _all_ ULT tests. For details about what compilers and build configurations we expect, 
-refer to instructions for [building](https://github.com/intel/compute-runtime/blob/master/BUILD.md) the driver.
-Make sure you adhere to our coding standard - this will be verified by clang-format and clang-tidy
+Make sure it builds and passes _all_ ULT tests. For details about what compilers
+and build configurations we expect, refer to instructions for
+[building](https://github.com/intel/compute-runtime/blob/master/BUILD.md) the driver.
+Make sure you adhere to our
+[coding standard](https://github.com/intel/compute-runtime/blob/master/GUIDELINES.md);
+this will be verified by clang-format and clang-tidy
 (tool configuration is already included in NEO repository).
 
 ### 2. Certificate of origin
-In order to get a clear contribution chain of trust we use the [signed-off-by language](https://01.org/community/signed-process) used by the Linux kernel project. 
+In order to get a clear contribution chain of trust we use the
+[signed-off-by language](https://01.org/community/signed-process) used by the Linux kernel project.
 Please make sure your commit message adheres to this guideline.
 
 ### 3. Patch submission
@@ -27,7 +31,8 @@ the requirements above. Make sure your commit message follows these rules:
 
 ### 4. Initial (cursory) review
 
-One of NEO maintainers will do an initial (brief) review of your code. We will let you know if anything major is missing.
+One of NEO maintainers will do an initial (brief) review of your code.
+We will let you know if anything major is missing.
 
 ### 5. Verification
 
@@ -37,13 +42,15 @@ We'll double-check that your code meets all of our minimal quality expectations.
 * Pass ULTs for all supported platforms
 * Pass clang-format check with the configuration contained within repository
 * Pass clang-tidy check with the configuration contained within repository
-* Pass sanity testing (test content recommendation for the external community will be provided in the future)
- 
+* Pass sanity testing
+(test content recommendation for the external community will be provided in the future)
+
 When all the automated checks are confirmed to be passing, we will start actual code review process.
 
 ### 6. Code review
 
-We'll make sure that your code fits within the architecture and design of NEO, is readable and maintainable. Please make sure to address our questions and concerns. 
+We'll make sure that your code fits within the architecture and design of NEO, is readable
+and maintainable. Please make sure to address our questions and concerns.
 
 ### 7. Patch disposition
 
@@ -57,6 +64,7 @@ Your patch may be reverted later in case of major regression that was not detect
 
 ## Intel Employees
 
-If you are an Intel Employee *and* you want to contribute to NEO as part of your regular job duties, please:
+If you are an Intel Employee *and* you want to contribute to NEO as part of your regular job duties
+please:
 * Contact us in advance
-* Make sure your github account is linked to your intel.com email address
+* Make sure your github account is linked to your intel.com email address

FAQ.md

@@ -1,6 +1,9 @@
 
 # Frequently asked questions
 
+For OpenCL specific questions,
+see the [OpenCL FAQ](https://github.com/intel/compute-runtime/blob/master/opencl/doc/FAQ.md).
+
 ## OS support
 
 ### Which Linux versions does NEO support?
@@ -27,10 +30,6 @@ and/or Windows update. Features available in github will be available on Windows
 
 Note: Older platforms (e.g. Broadwell) are considered to be in maintenance mode for Windows.
 
-### Does NEO support Android?
-
-The code can be ported and cross-compiled for Android systems. It is our long-term intention to offer that option.
-
 ## Platform support
 
 ### Which Intel platforms are supported by the driver?
@@ -42,135 +41,17 @@ See [README.md](https://github.com/intel/compute-runtime/blob/master/README.md).
 To check support for any device, you can follow these steps:
 1. Go to [Ark]( https://ark.intel.com) and find your Device ID
 1. Find the corresponding device ID label in [GMM]( https://github.com/intel/gmmlib/blob/master/Source/inc/common/igfxfmid.h)
-1. Check if this device ID label is enumerated in the [supported device list](https://github.com/intel/compute-runtime/blob/master/runtime/dll/linux/devices/devices_base.inl)
+1. Check if this device ID label is enumerated in the
+[supported device list](https://github.com/intel/compute-runtime/blob/master/opencl/source/dll/linux/devices/devices_base.inl)
 
 ### When will support for platform X be added?
 
 We will start adding platform support after platform is disclosed by Intel.
 It is our intention to offer full support ahead of platform's market availability.
 
-## OpenCL version
-
-### Which version of OpenCL is supported?
-
-See [README.md](https://github.com/intel/compute-runtime/blob/master/README.md).
-
-### Which platforms will receive OpenCL 2.2 support?
-
-Any platforms supporting OpenCL 2.1 are eligible for move to OpenCL 2.2.
-
-### How can I enable OpenCL 2.1 on the Apollo Lake / Broxton platform?
-
-You can enable a higher version of OpenCL using the ForceOCLVersion debug flag.
-
-## Feature: cl_cache
-
-### What is cl_cache?
-
-This is a mechanism to cache binary representations of OpenCL kernels provided in text form by the application.
-By storing the binary representations, compiling is required only the first time, which improves performance.
-
-### How can cl_cache be enabled?
-
-In the working directory, manually create *cl_cache* directory.
-The driver will use this directory to store the binary representations of the compiled kernels.
-Note: This will work on all supported OSes.
-
-### Configuring cl_cache location
-
-Cached kernels can be stored in a different directory than the default one. This is useful when the application is installed into a directory for which the user doesn't have permissions.
-
-#### Linux configuration
-
-Set the environment variable named `cl_cache_dir` to new location of cl_cache directory.
-
-#### Example:
-
-If the application's directory is `/home/user/Document`, by default cl_cache will be stored in `/home/user/Document/cl_cache`.
-If the new path should be `/home/user/Desktop/cl_cache_place`, set environment variable `cl_cache_dir` to `/home/user/Desktop/cl_cache_place`.
-```bash
-export cl_cache_dir=/home/user/Desktop/cl_cache_place
-```
-
-Subsequent application runs with passed source code and `cl_cache_dir` environment variable set will reuse previously cached kernel binaries instead of compiling kernels from source.
-
-#### Windows configuration
-
-To set the new location of cl_cache directory - in the registry `HKEY_LOCAL_MACHINE\SOFTWARE\Intel\IGFX\OCL`:
-1. add key `cl_cache_dir`
-1. add string value named <path_to_app> to `cl_cache_dir` key
-1. set data of added value to desired location of cl_cache
-
-#### Example:
-
-If application is located in `C:\Program Files\application\app.exe`, by default cl_cache will be stored in `C:\Program Files\application\cl_cache`.
-If the new path should be `C:\Users\USER\Documents\application\cl_cache`, to subkey `HKEY_LOCAL_MACHINE\SOFTWARE\Intel\IGFX\OCL\cl_cache_dir` add string value named `C:\Program Files\application\app.exe` with data `C:\Users\USER\Documents\application\cl_cache`.
-
-e.g.
-string value : `HKEY_LOCAL_MACHINE\SOFTWARE\Intel\IGFX\OCL\cl_cache_dir\C:\Program Files\application\app.exe`
-data : `C:\Users\USER\Documents\application\cl_cache`
-
-Neo will look for string value (REG_SZ) `C:\Program Files\application\app.exe` in key `HKEY_LOCAL_MACHINE\SOFTWARE\Intel\IGFX\OCL\cl_cache_dir`. Data of this string value will be used as new cl_cache dump directory for this specific application.
-
-### What are the known limitations of cl_cache?
-
-1. Not thread safe. (Workaround: Make sure your clBuildProgram calls are executed in thread safe fashion.)
-1. Binary representation may not be compatible between various versions of NEO and IGC drivers. (Workaround: Manually empty *cl_cache* directory prior to update)
-1. Cache is not automatically cleaned. (Workaround: Manually empty *cl_cache* directory)
-1. Cache may exhaust disk space and cause further failures.  (Workaround: Monitor and manually empty *cl_cache* directory)
-1. Cache is not process safe.
-
-## Feature: Out of order queues
-
-### Implementation details of out of order queues implementation
-
-Current implementation of out of order queues allows multiple kernels to be run concurently. This allows for better device utilization in scenarios where single kernel
-doesn't fill whole device.
-
-More details can be found here:
-
-https://github.com/intel/compute-samples/tree/master/compute_samples/applications/commands_aggregation
-
-https://www.iwocl.org/wp-content/uploads/iwocl-2019-michal-mrozek-intel-breaking-the-last-line-of-performance-border.pdf
-
-### Known issues and limitations
-
-1. Turning on profiling on out of order command queue serializes kernel execution.
-1. Blocking command queue with user events blocks all further submissions until event is unblocked.
-1. Commands blocked by user events, when unblocked are serialized as well.
-
-## Feature: Double-precision emulation (FP64)
-
-By default NEO driver enables double precision operations only on platforms with supporting hardware. This is signified by exposing the "cl_khr_fp64" extension in the extension string. For other platforms, this support can be emulated by the compiler (IGC).
-
-### How do I enable emulation?
-
-FP64 emulation can only be enabled on Linux. There are two settings that have to be set.
-
-#### Runtime setting:
-
-There are two ways you can enable this feature in NEO:
-
-* Set an environment variable **OverrideDefaultFP64Settings** to **1**:
-`OverrideDefaultFP64Settings=1`
-
-* In **igdrcl.config** configuration file in the same directory as application binary (you may have to create this file) add a line as such:
-`OverrideDefaultFP64Settings = 1`
-
-#### Compiler setting:
-
-IGC reads flags only from environment, so set **IGC_EnableDPEmulation** to **1** as such:
-`IGC_EnableDPEmulation=1`
-
-After both settings have been set you can run the application normally.
-
-### Known issues and limitations
-
-Intel does not claim full specification conformance when using emulated mode. We reserve the right to not fix issues that appear only in emulation mode. Performance degradation is to be expected and has not been measured by Intel.
-
 ## Who are we?
 
-NEO OpenCL team is part of VTT (Visual Technologies Team). 
+NEO OpenCL team is part of VTT (Visual Technologies Team).
 Historically, our team was responsible for delivery of the closed source OpenCL driver for Windows, Linux, and Android.
 
 Most of the developers are located in Poland (UTC+1 timezone).

README.md

@@ -7,35 +7,60 @@ converge Intel's development efforts on OpenCL(TM) compute stacks supporting the
 GEN graphics hardware architecture.
 
 Please refer to http://01.org/compute-runtime for additional details regarding Intel's
-motivation and intentions wrt OpenCL support in the open source.
+motivation and intentions wrt OpenCL support in open source.
 
 ## License
 
 The Intel(R) Graphics Compute Runtime for OpenCL(TM) is distributed under the MIT License.
 
 You may obtain a copy of the License at: https://opensource.org/licenses/MIT
 
+## Supported Platforms
+
+* Intel Core Processors with Gen8 graphics devices (formerly Broadwell) - OpenCL 2.1
+* Intel Core Processors with Gen9 graphics devices (formerly Skylake, Kaby Lake, Coffee Lake) - OpenCL 2.1
+* Intel Atom Processors with Gen9 graphics devices (formerly Apollo Lake, Gemini Lake) - OpenCL 1.2
+* Intel Core Processors with Gen11 graphics devices (formerly Ice Lake) - OpenCL 2.1
+* Intel Core Processors with Gen12 graphics devices (formerly Tiger Lake) - OpenCL 2.1
+
+## Release cadence
+
+* Once a week, we run extended validation cycle on a selected driver.
+* When the extended validation cycle tests pass, the corresponding commit on github is tagged using
+the format yy.ww.bbbb (yy - year, ww - work week, bbbb - incremental build number).
+* Typically for weekly tags we will post a binary release (e.g. deb).
+* Quality level of the driver (per platform) will be provided in the Release Notes.
+
 ## Installation Options
 
-To allow Neo accessing GPU device make sure user has permissions to files /dev/dri/renderD*.
+To allow NEO accessing GPU device make sure user has permissions to files /dev/dri/renderD*.
 
-Under Ubuntu* or Centos* user must be in video group. In Fedora* all users by default have access to /dev/dri/renderD* files.
+Under Ubuntu* or Centos* user must be in video group.
+In Fedora* all users by default have access to /dev/dri/renderD* files.
 
 ### Via system package manager
 
-NEO is available for installation on a variety of Linux distributions and can be installed via the distro's package manager. 
+NEO is available for installation on a variety of Linux distributions
+and can be installed via the distro's package manager.
 
 For example on Ubuntu* 19.04, 19.10:
 
 ```
 apt-get install intel-opencl-icd
 ```
 
-Procedures for other [distributions](https://github.com/intel/compute-runtime/blob/master/documentation/DISTRIBUTIONS.md).
+Procedures for other
+[distributions](https://github.com/intel/compute-runtime/blob/master/documentation/DISTRIBUTIONS.md).
+
+## Linking applications
+
+When building applications, they should link with ICD loader library (ocl-icd).
+Directly linking to the runtime library (igdrcl) is not supported.
 
 ### Manual download
 
-.deb packages for Ubuntu are provided along with installation instructions and Release Notes on the [release page](https://github.com/intel/compute-runtime/releases)
+.deb packages for Ubuntu are provided along with installation instructions and
+Release Notes on the [release page](https://github.com/intel/compute-runtime/releases)
 
 ## Dependencies
 
@@ -44,54 +69,37 @@ Procedures for other [distributions](https://github.com/intel/compute-runtime/bl
 
 ## Optional dependencies
 
-To enable [cl_intel_va_api_media_sharing](https://www.khronos.org/registry/OpenCL/extensions/intel/cl_intel_va_api_media_sharing.txt) extension,
-the following packages are required:
+To enable
+[cl_intel_va_api_media_sharing](https://www.khronos.org/registry/OpenCL/extensions/intel/cl_intel_va_api_media_sharing.txt)
+extension, the following packages are required:
 
 * libdrm - https://anongit.freedesktop.org/git/mesa/drm.git
 * libva - https://github.com/intel/libva.git
 
-## Supported Platforms
-
-* Intel Core Processors with Gen8 graphics devices (formerly Broadwell) - OpenCL 2.1
-* Intel Core Processors with Gen9 graphics devices (formerly Skylake, Kaby Lake, Coffee Lake) - OpenCL 2.1
-* Intel Atom Processors with Gen9 graphics devices (formerly Apollo Lake, Gemini Lake) - OpenCL 1.2
-* Intel Core Processors with Gen11 graphics devices (formerly Ice Lake) - OpenCL 2.1
-* Intel Core Processors with Gen12 graphics devices (formerly Tiger Lake) - OpenCL 2.1
-
-## Release cadence
-
-* Once a week, we run extended validation cycle on a selected driver.
-* When the extended validation cycle tests pass, the corresponding commit on github is tagged using the format yy.ww.bbbb 
-(yy - year, ww - work week, bbbb - incremental build number).
-* Typically for weekly tags we will post a binary release (e.g. deb).
-* Quality level of the driver (per platform) will be provided in the Release Notes.
-
-## Linking applications
-
-When building applications, they should link with ICD loader library (ocl-icd).
-Directly linking to the runtime library (igdrcl) is not supported.
-
-## Tutorial applications
-
-The [Intel(R) GPU Compute Samples repository](https://github.com/intel/compute-samples/blob/master/compute_samples/applications/usm_hello_world/README.md) 
-has sample source code to demonstrate features of Intel(R) Graphics Compute Runtime for OpenCL(TM) Driver.
-
 ## How to provide feedback
 
-By default, please submit an issue using native github.com interface: https://github.com/intel/compute-runtime/issues.
+By default, please submit an issue using native github.com [interface](https://github.com/intel/compute-runtime/issues).
 
 ## How to contribute
 
 Create a pull request on github.com with your patch. Make sure your change is cleanly building and passing ULTs.
 A maintainer will contact you if there are questions or concerns.
-See [contribution guidelines](https://github.com/intel/compute-runtime/blob/master/documentation/CONTRIBUTING.md) for more details.
+See
+[contribution guidelines](https://github.com/intel/compute-runtime/blob/master/documentation/CONTRIBUTING.md)
+for more details.
 
 ## See also
 
-* [OpenCL on Linux guide](https://github.com/bashbaug/OpenCLPapers/blob/markdown/OpenCLOnLinux.md)
-* [Interoperability with VTune](https://github.com/intel/compute-runtime/blob/master/opencl/doc/VTUNE.md)
 * [Contribution guidelines](https://github.com/intel/compute-runtime/blob/master/documentation/CONTRIBUTING.md)
-* [Known issues and limitations](https://github.com/intel/compute-runtime/blob/master/opencl/doc/LIMITATIONS.md)
 * [Frequently Asked Questions](https://github.com/intel/compute-runtime/blob/master/FAQ.md)
 
-___(*) Other names and brands may be claimed as property of others.___
+### OpenCL specific
+
+* [OpenCL on Linux guide](https://github.com/bashbaug/OpenCLPapers/blob/markdown/OpenCLOnLinux.md)
+* [Intel(R) GPU Compute Samples](https://github.com/intel/compute-samples)
+* [Frequently Asked Questions](https://github.com/intel/compute-runtime/blob/master/opencl/doc/FAQ.md)
+* [Known issues and limitations](https://github.com/intel/compute-runtime/blob/master/opencl/doc/LIMITATIONS.md)
+* [Interoperability with VTune](https://github.com/intel/compute-runtime/blob/master/opencl/doc/VTUNE.md)
+* [OpenCL Conformance Tests](https://github.com/KhronosGroup/OpenCL-CTS/)
+
+___(*) Other names and brands may be claimed as property of others.___