From 0e9d7e6b639078cd27db8a63c5071b5fb4425480 Mon Sep 17 00:00:00 2001
From: tomasz-platek <tomasz.platek@imgtec.com>
Date: Thu, 4 Jul 2024 14:30:08 +0200
Subject: [PATCH 1/2] Publish the cl_img_bitwise_ops extension specification.

---
 extensions/cl_img_bitwise_ops.asciidoc | 118 +++++++++++++++++++++++++
 extensions/extensions.txt              |   2 +
 2 files changed, 120 insertions(+)
 create mode 100644 extensions/cl_img_bitwise_ops.asciidoc

diff --git a/extensions/cl_img_bitwise_ops.asciidoc b/extensions/cl_img_bitwise_ops.asciidoc
new file mode 100644
index 00000000..43d7c7d3
--- /dev/null
+++ b/extensions/cl_img_bitwise_ops.asciidoc
@@ -0,0 +1,118 @@
+:data-uri:
+:icons: font
+include::../config/attribs.txt[]
+:source-highlighter: coderay
+
+= cl_img_bitwise_ops
+
+== Name Strings
+
+`cl_img_bitwise_ops`
+
+== Contact
+
+Imagination Technologies Developer Forum: +
+https://forums.imgtec.com/
+
+Tomasz Platek, Imagination Technologies (Tomasz.Platek 'at' imgtec.com)
+
+== Contributors
+
+CY Cheng, Imagination Technologies. +
+Tomasz Platek, Imagination Technologies.
+
+== Notice
+
+Copyright (c) 2024 Imagination Technologies Ltd. All Rights Reserved.
+
+== Status
+
+Final Draft
+
+== Version
+
+Built On: {docdate} +
+Version: Major.Minor.Patch
+
+== Dependencies
+
+This extension is written against the OpenCL C Specification Version V3.0.16.
+
+== Overview
+
+This extension adds built-in functions that expose the bitwise operations of Imagination GPU IP that are not accessible by standard OpenCL C functions.
+
+== New OpenCL C Feature Names
+
+[source,c]
+----
+__opencl_img_bit_interleave
+----
+
+== New OpenCL C Functions
+
+Performs the bit interleave operation:
+
+[source,c]
+----
+gentype img_bit_interleave(gentype a, gentype b);
+----
+
+== Modifications to the OpenCL C Specification
+
+(Add to Table 16 - Built-in Scalar and Vector Argument Common Functions in Section 6.15.4 - Common Functions) ::
++
+--
+[cols="1,2",options="header"]
+|====
+| Function | Description
+| gentype *img_bit_interleave*(gentype a, gentype b)
+    a| `img_bit_interleave` interleaves the first `n` bits from two sources where `n` is half of the size of gentype in bits.
+
+For `a` and `b`, where a0 and b0 are the least significant bits:
+[source]
+----
+a = a(N-1)\|a(N-2)\|a(N-3)\|...\|a3\|a2\|a1\|a0
+b = b(N-1)\|b(N-2)\|b(N-3)\|...\|b3\|b2\|b1\|b0
+----
+
+the output is:
+[source]
+----
+res = b(N/2-1)\|a(N/2-1)\|b(N/2-2)\|a(N/2-2)\|b(N/2-3)\|a(N/2-3)\|...\|b3\|a3\|b2\|a2\|b1\|a1\|b0\|a0
+----
+so the sizes of `a`,`b`, and `res` are equal.
+
+Requires that the `__opencl_img_bit_interleave` feature macro is defined.
+|====
+--
+
+== Coding Sample
+
+This coding sample shows how to use the *img_bit_interleave* function:
+[source]
+----
+int4 a = (int4) ( 0x00000000, 0x00000000, 0x0000FFFF, 0xFFFFFFFF);
+int4 b = (int4) ( 0xFFFFFFFF, 0x0000FFFF, 0x00000000, 0x00000000);
+
+int4 res = img_bit_interleave(a,b);
+
+printf("res = [ 0x%x 0x%x 0x%x 0x%x]\n", res.s0, res.s1, res.s2, res.s3);
+----
+
+Executing a work-item of this kernel gives the following result:
+[source]
+----
+res = [ 0xaaaaaaaa 0xaaaaaaaa 0x55555555 0x55555555]
+----
+
+== Version History
+
+[cols="5,15,15,70"]
+[grid="rows"]
+[options="header"]
+|====
+| Version | Date       | Author        | Changes
+| 1.0.0   | 2024-06-19 | Tomasz Platek | *Initial revision*
+|====
+
diff --git a/extensions/extensions.txt b/extensions/extensions.txt
index 573ec116..7592dcbb 100644
--- a/extensions/extensions.txt
+++ b/extensions/extensions.txt
@@ -61,6 +61,8 @@ include::cl_arm_scheduling_controls.asciidoc[]
 == Imagination Technologies Extensions
 :leveloffset: 2
 <<<
+include::cl_img_bitwise_ops.asciidoc[]
+<<<
 include::cl_img_cached_allocations.asciidoc[]
 <<<
 include::cl_img_cancel_command.asciidoc[]

From 88190fb862f4a671084a99d52e4c9dccbc135daf Mon Sep 17 00:00:00 2001
From: tomasz-platek <165791413+tomasz-platek@users.noreply.github.com>
Date: Wed, 10 Jul 2024 09:54:53 +0200
Subject: [PATCH 2/2] Update extensions/cl_img_bitwise_ops.asciidoc

Listing the initial extension version.

Co-authored-by: Ben Ashbaugh <ben.ashbaugh@intel.com>
---
 extensions/cl_img_bitwise_ops.asciidoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/extensions/cl_img_bitwise_ops.asciidoc b/extensions/cl_img_bitwise_ops.asciidoc
index 43d7c7d3..fbbd370f 100644
--- a/extensions/cl_img_bitwise_ops.asciidoc
+++ b/extensions/cl_img_bitwise_ops.asciidoc
@@ -32,7 +32,7 @@ Final Draft
 == Version
 
 Built On: {docdate} +
-Version: Major.Minor.Patch
+Version: 1.0.0
 
 == Dependencies