Docs update for v1.20.0

Author: dbabokin

ispc.html

@@ -116,6 +116,7 @@ <h1 class="title">Intel® ISPC User's Guide</h1>
 <li><a class="reference internal" href="#updating-ispc-programs-for-changes-in-ispc-1-17-0">Updating ISPC Programs For Changes In ISPC 1.17.0</a></li>
 <li><a class="reference internal" href="#updating-ispc-programs-for-changes-in-ispc-1-18-0">Updating ISPC Programs For Changes In ISPC 1.18.0</a></li>
 <li><a class="reference internal" href="#updating-ispc-programs-for-changes-in-ispc-1-19-0">Updating ISPC Programs For Changes In ISPC 1.19.0</a></li>
+<li><a class="reference internal" href="#updating-ispc-programs-for-changes-in-ispc-1-20-0">Updating ISPC Programs For Changes In ISPC 1.20.0</a></li>
 </ul>
 </li>
 <li><a class="reference internal" href="#getting-started-with-ispc">Getting Started with ISPC</a><ul>
@@ -534,6 +535,15 @@ <h2>Updating ISPC Programs For Changes In ISPC 1.19.0</h2>
 and <tt class="docutils literal">typename</tt>.</p>
 <p><tt class="docutils literal">ISPC_FP16_SUPPORTED</tt> macro was introduced for the targets supporting FP16.</p>
 </div>
+<div class="section" id="updating-ispc-programs-for-changes-in-ispc-1-20-0">
+<h2>Updating ISPC Programs For Changes In ISPC 1.20.0</h2>
+<p>New version of <cite>sse4</cite> targets were added, now you can specify either <cite>sse4.1</cite>
+or <cite>sse4.2</cite>, for example <cite>sse4.2-i32x4</cite>. The changes are fully backward
+compatible, meaning that <cite>sse4</cite> versions are still accepted and aliased to
+<cite>sse4.2</cite>. Multi-target compilation accepts only one of <cite>sse4</cite>/<cite>sse4.1</cite>/<cite>sse4.2</cite>
+targets. All of these targets will produce an object file with <cite>sse4</cite> suffix in
+multi-target compilation.</p>
+</div>
 </div>
 <div class="section" id="getting-started-with-ispc">
 <h1>Getting Started with ISPC</h1>
@@ -753,7 +763,7 @@ <h2>Selecting The Compilation Target</h2>
 <td>AVX (2010-2011 era Intel CPUs)</td>
 </tr>
 <tr><td>avx2</td>
-<td>AVX 2 target (2013- Intel &quot;Haswell&quot; CPUs)</td>
+<td>AVX 2 target (2013- Intel codename Haswell CPUs)</td>
 </tr>
 <tr><td>avx512knl</td>
 <td>AVX 512 target (Xeon Phi chips codename Knights Landing)</td>
@@ -770,18 +780,24 @@ <h2>Selecting The Compilation Target</h2>
 <tr><td>sse2</td>
 <td>SSE2 (early 2000s era x86 CPUs)</td>
 </tr>
-<tr><td>sse4</td>
-<td>SSE4 (generally 2008-2010 Intel CPUs)</td>
+<tr><td>sse4.1</td>
+<td>SSE4.1 (2007 Intel codename Penryn CPUs)</td>
+</tr>
+<tr><td>sse4.2</td>
+<td>SSE4.2 (2008-2010 Intel codename Nehalem CPUs)</td>
 </tr>
 <tr><td>gen9</td>
 <td>Intel Gen9 GPU</td>
 </tr>
-<tr><td>xehpg</td>
-<td>Intel XeHPG GPU</td>
-</tr>
 <tr><td>xelp</td>
 <td>Intel XeLP GPU</td>
 </tr>
+<tr><td>xehpg</td>
+<td>Intel Arc GPU</td>
+</tr>
+<tr><td>xehpc</td>
+<td>Intel Ponte Vecchio GPU</td>
+</tr>
 </tbody>
 </table>
 <p>Consult your CPU's manual for specifics on which vector instruction set it
@@ -834,20 +850,38 @@ <h2>Selecting The Compilation Target</h2>
 <tr><td>sse2-i32x8</td>
 <td>sse2-x2</td>
 </tr>
-<tr><td>sse4-i32x4</td>
+<tr><td>sse4.2-i32x4</td>
 <td>sse4</td>
 </tr>
-<tr><td>sse4-i32x8</td>
+<tr><td>sse4.2-i32x8</td>
 <td>sse4-x2</td>
 </tr>
-<tr><td>sse4-i8x16</td>
+<tr><td>sse4.2-i8x16</td>
 <td>n/a</td>
 </tr>
-<tr><td>sse4-i16x8</td>
+<tr><td>sse4.2-i16x8</td>
 <td>n/a</td>
 </tr>
 </tbody>
 </table>
+<p>The full list of supported targets is below.</p>
+<p>x86 targets:</p>
+<p><tt class="docutils literal"><span class="pre">sse2-i32x4</span></tt>, <tt class="docutils literal"><span class="pre">sse2-i32x8</span></tt>, <tt class="docutils literal"><span class="pre">sse4.1-i8x16</span></tt>, <tt class="docutils literal"><span class="pre">sse4.1-i16x8</span></tt>, <tt class="docutils literal"><span class="pre">sse4.1-i32x4</span></tt>,
+<tt class="docutils literal"><span class="pre">sse4.1-i32x8</span></tt>, <tt class="docutils literal"><span class="pre">sse4.2-i8x16</span></tt>, <tt class="docutils literal"><span class="pre">sse4.2-i16x8</span></tt>, <tt class="docutils literal"><span class="pre">sse4.2-i32x4</span></tt>, <tt class="docutils literal"><span class="pre">sse4.2-i32x8</span></tt>,
+<tt class="docutils literal"><span class="pre">avx1-i32x4</span></tt>, <tt class="docutils literal"><span class="pre">avx1-i32x8</span></tt>, <tt class="docutils literal"><span class="pre">avx1-i32x16</span></tt>, <tt class="docutils literal"><span class="pre">avx1-i64x4</span></tt>, <tt class="docutils literal"><span class="pre">avx2-i8x32</span></tt>,
+<tt class="docutils literal"><span class="pre">avx2-i16x16</span></tt>, <tt class="docutils literal"><span class="pre">avx2-i32x4</span></tt>, <tt class="docutils literal"><span class="pre">avx2-i32x8</span></tt>, <tt class="docutils literal"><span class="pre">avx2-i32x16</span></tt>, <tt class="docutils literal"><span class="pre">avx2-i64x4</span></tt>,
+<tt class="docutils literal"><span class="pre">avx512knl-x16</span></tt>, <tt class="docutils literal"><span class="pre">avx512skx-x4</span></tt>, <tt class="docutils literal"><span class="pre">avx512skx-x8</span></tt>, <tt class="docutils literal"><span class="pre">avx512skx-x16</span></tt>, <tt class="docutils literal"><span class="pre">avx512skx-x32</span></tt>,
+<tt class="docutils literal"><span class="pre">avx512skx-x64</span></tt>, <tt class="docutils literal"><span class="pre">avx512spr-x4</span></tt>, <tt class="docutils literal"><span class="pre">avx512spr-x8</span></tt>, <tt class="docutils literal"><span class="pre">avx512spr-x16</span></tt>, <tt class="docutils literal"><span class="pre">avx512spr-x32</span></tt>,
+<tt class="docutils literal"><span class="pre">avx512spr-x64</span></tt>.</p>
+<p>Neon targets:</p>
+<p><tt class="docutils literal"><span class="pre">neon-i8x16</span></tt>, <tt class="docutils literal"><span class="pre">neon-i16x8</span></tt>, <tt class="docutils literal"><span class="pre">neon-i32x4</span></tt>, <tt class="docutils literal"><span class="pre">neon-i32x8</span></tt>.</p>
+<p>Xe targets:</p>
+<p><tt class="docutils literal"><span class="pre">gen9-x8</span></tt>, <tt class="docutils literal"><span class="pre">gen9-x16</span></tt>, <tt class="docutils literal"><span class="pre">xelp-x8</span></tt>, <tt class="docutils literal"><span class="pre">xelp-x16</span></tt>, <tt class="docutils literal"><span class="pre">xehpg-x8</span></tt>, <tt class="docutils literal"><span class="pre">xehpg-x16</span></tt>, <tt class="docutils literal"><span class="pre">xehpc-x16</span></tt>, <tt class="docutils literal"><span class="pre">xehpc-x32</span></tt>.</p>
+<p>Note that <tt class="docutils literal">sse4.1</tt> and <tt class="docutils literal">sse4.2</tt> targets may not be used together in
+multi-target compilation. While the auto-dispatch code will correctly detect
+the difference between these two ISAs, they both yield a binary with <tt class="docutils literal">sse4</tt>
+suffix. This limitation is to maintain backward compatibility with build
+systems expecting <tt class="docutils literal">sse4</tt> suffix.</p>
 <p>Finally, <tt class="docutils literal"><span class="pre">--target-os</span></tt> selects the target operating system. Depending on
 your host <tt class="docutils literal">ispc</tt> may support Windows, Linux, macOS, Android, iOS and PS4/PS5
 targets. Running <tt class="docutils literal">ispc <span class="pre">--help</span></tt> and looking at the output for the <tt class="docutils literal"><span class="pre">--target-os</span></tt>
@@ -3073,7 +3107,7 @@ <h2>Task Parallel Execution</h2>
 <h2>Task Parallelism: &quot;launch&quot; and &quot;sync&quot; Statements</h2>
 <p>One option for combining task-parallelism with <tt class="docutils literal">ispc</tt> is to just use
 regular task parallelism in the C/C++ application code (be it through
-Intel® Thread Building Blocks, OpenMP or another task system), and
+Intel® oneAPI Threading Building Blocks, OpenMP or another task system), and
 for tasks to use <tt class="docutils literal">ispc</tt> for SPMD parallelism across the vector lanes as
 appropriate.  Alternatively, <tt class="docutils literal">ispc</tt> also has support for launching tasks
 from <tt class="docutils literal">ispc</tt> code.  (Check the <tt class="docutils literal">examples/mandelbrot_tasks</tt> example to

ispc_for_xe.html

@@ -119,9 +119,9 @@ <h2>Environment</h2>
 Compute Runtime</a> on Linux
 or <a class="reference external" href="https://www.intel.com/content/www/us/en/download-center/home.html">Intel(R) Graphics Driver for Windows</a> on
 Windows.  Additionally you need <a class="reference external" href="https://github.com/oneapi-src/level-zero/releases">Level Zero Loader</a>.</p>
-<p>To use ISPC Run Time for CPU on Linux you need to have <tt class="docutils literal">OpenMP runtime</tt>
+<p>To use ISPC Run Time for CPU on Linux you need to have <tt class="docutils literal">Intel(R) oneAPI Threading Basic Blocks</tt>
 installed on your system. Consult your Linux distribution documentation for the
-installation of OpenMP runtime instructions.</p>
+installation of TBB runtime instructions.</p>
 </div>
 <div class="section" id="basic-command-line-options">
 <h2>Basic Command-line Options</h2>
@@ -192,11 +192,25 @@ <h2>ISPCRT Objects</h2>
 data allocated in the USM are valid both on the host and on the device.  Also,
 there is no need to explicitly handle data movement between the CPU and the
 GPU. This is handled automatically by the <tt class="docutils literal">oneAPI Level Zero</tt> runtime.</li>
-<li><tt class="docutils literal">Task queue</tt> - Each <tt class="docutils literal">device</tt> has a task (command) queue and executes
-commands from it. The execution may be asynchronous, which means that
-subsequent commands can begin executing before the previous ones complete.
-There are synchronization primitives available to make the execution
-synchronous.</li>
+<li><tt class="docutils literal">Task queue</tt> - each <tt class="docutils literal">device</tt> has a task (command) queue and executes
+commands from it. Commands may be executed simultaneously. To prevent that
+one should explicitly insert barriers in places where synchronization is
+required. <tt class="docutils literal">Task queue</tt> <tt class="docutils literal">sync</tt> method stops the host thread until GPU
+computation completed. For asynchronous computation, one should utilize
+<tt class="docutils literal">CommandQueue</tt> and <tt class="docutils literal">CommandList</tt> objects.</li>
+<li><tt class="docutils literal">CommandQueue</tt> - represents a logical input stream to the device and
+directly maps to L0 command queues.</li>
+<li><tt class="docutils literal">CommandList</tt> - represents commands to be executed on a command queue. It
+can be created by calling <tt class="docutils literal">createCommandList</tt> method of <tt class="docutils literal">CommandQueue</tt>
+object. Synchronization between all commands in list has to be done
+explicitly by putting barriers if needed. Fine-grained synchronization via
+<tt class="docutils literal">Events</tt> are not supported yet.</li>
+<li><tt class="docutils literal">Fence</tt> - is a synchronization primitive to communicate to the host that
+command list execution has completed. <tt class="docutils literal">Fence</tt> is created upon command list
+submission. It can be waited synchronously (<tt class="docutils literal">sync</tt>) and asynchronously
+(periodically checking <tt class="docutils literal">status</tt>). Fence has two states
+<tt class="docutils literal">ISPCRT_FENCE_UNSIGNALED</tt> and <tt class="docutils literal">ISPCRT_FENCE_SIGNALED</tt> returned by
+<tt class="docutils literal">status</tt> method.</li>
 <li><tt class="docutils literal">Barrier</tt> - synchronization primitive that can be inserted into a <tt class="docutils literal">task
 queue</tt> to make sure that all tasks previously inserted into this queue have
 completed execution. It is not needed to include <tt class="docutils literal">barrier</tt> between memory