From 1b9520a7ef5f5b5e4bae57aecb78c5ec47c28e75 Mon Sep 17 00:00:00 2001
From: Felipe de Azevedo Piovezan <felipe.de.azevedo.piovezan@intel.com>
Date: Thu, 16 Apr 2020 15:43:16 -0400
Subject: [PATCH] [SYCL][Doc] Add static local memory query extension.

This commit adds an extension defining a new query that allows a runtime to
query how much local memory is used by a given kernel in a given device.

Signed-off-by: Felipe de Azevedo Piovezan <felipe.de.azevedo.piovezan@intel.com>
---
 ...L_INTEL_static_local_memory_query.asciidoc | 105 ++++++++++++++++++
 1 file changed, 105 insertions(+)
 create mode 100644 sycl/doc/extensions/StaticLocalMemoryQuery/SYCL_INTEL_static_local_memory_query.asciidoc

diff --git a/sycl/doc/extensions/StaticLocalMemoryQuery/SYCL_INTEL_static_local_memory_query.asciidoc b/sycl/doc/extensions/StaticLocalMemoryQuery/SYCL_INTEL_static_local_memory_query.asciidoc
new file mode 100644
index 000000000000..74f3570c559d
--- /dev/null
+++ b/sycl/doc/extensions/StaticLocalMemoryQuery/SYCL_INTEL_static_local_memory_query.asciidoc
@@ -0,0 +1,105 @@
+= SYCL_INTEL_static_local_memory_query
+
+:source-highlighter: coderay
+:coderay-linenums-mode: table
+
+// This section needs to be after the document title.
+:doctype: book
+:toc2:
+:toc: left
+:encoding: utf-8
+:lang: en
+
+:blank: pass:[ +]
+
+// Set the default source code type in this document to C++,
+// for syntax highlighting purposes.  This is needed because
+// docbook uses c++ and html5 uses cpp.
+:language: {basebackend@docbook:c++:cpp}
+
+// This is necessary for asciidoc, but not for asciidoctor
+:cpp: C++
+
+== Introduction
+IMPORTANT: This specification is a draft.
+
+NOTE: Khronos(R) is a registered trademark and SYCL(TM) and SPIR(TM) are trademarks of The Khronos Group Inc.  OpenCL(TM) is a trademark of Apple Inc. used by permission by Khronos.
+
+NOTE: This document is better viewed when rendered as html with asciidoctor.  GitHub does not render image icons.
+
+This document describes an extension that allows querying the amount of local memory statically allocated by a kernel.
+
+== Name Strings
+
++SYCL_INTEL_static_local_memory_query+
+
+== Notice
+
+Copyright (c) 2020 Intel Corporation.  All rights reserved.
+
+== Status
+
+Working Draft
+
+This is a preview extension specification, intended to provide early access to a feature for review and community feedback. When the feature matures, this specification may be released as a formal extension.
+
+Because the interfaces defined by this specification are not final and are subject to change they are not intended to be used by shipping software products.
+
+== Version
+
+Built On: {docdate} +
+Revision: 1
+
+== Contact
+Felipe de Azevedo Piovezan, Intel (felipe 'dot' de 'dot' azevedo 'dot' piovezan 'at' intel 'dot' com)
+
+== Dependencies
+
+This extension is written against the SYCL 1.2.1 specification, Revision 6.
+
+This extension depends on +SYCL_INTEL_device_specific_kernel_queries+.
+
+== Overview
+
+SYCL 1.2.1 already provides an API to query the amount of local memory available on
+devices (`device::get_info<info::device::local_mem_size>()`). This can be used as
+an upper bound for the amount of memory available to local accessors. However,
+kernel compilers are allowed to make use of local memory, effectively reducing
+the amount of memory available for local accessors. This extension adds a query
+to determine the amount of statically allocated local memory used by kernels
+(`kernel::get_info<info::kernel_device_specific::local_static_mem_used>(device)`).
+
+== Modifications of SYCL 1.2.1 Specification
+
+=== Add Row to Table 4.85 in Section 4.8.7 (Kernel class)
+
+==== New row:
+
+[width="40%",frame="topbot",options="header,footer"]
+|======================
+|Kernel Device-specific Information Descriptors |Return type |Description
+|`info::kernel_device_specific::local_static_mem_used` | cl_ulong | Returns the minimum amount of local memory, in bytes, statically allocated in a kernel. This value may include any local memory needed by an implementation to execute the kernel, including that used by the language built-ins.
+|======================
+
+== Issues
+
+None.
+
+== Revision History
+
+[cols="5,15,15,70"]
+[grid="rows"]
+[options="header"]
+|========================================
+|Rev|Date|Author|Changes
+|1|2020-04-15|Felipe de Azevedo Piovezan|*Initial public working draft*
+|========================================
+
+//************************************************************************
+//Other formatting suggestions:
+//
+//* Use *bold* text for host APIs, or [source] syntax highlighting.
+//* Use +mono+ text for device APIs, or [source] syntax highlighting.
+//* Use +mono+ text for extension names, types, or enum values.
+//* Use _italics_ for parameters.
+//************************************************************************