From 59c28bc024a9e02f773f3b4201a42d9ac494ba6b Mon Sep 17 00:00:00 2001 From: Mariya Podchishchaeva Date: Wed, 23 Jun 2021 10:15:44 +0300 Subject: [PATCH 1/4] [SPIR-V][Doc] Add SPV_INTEL_debug_module spec --- .../SPIRV/SPV_INTEL_debug_module.asciidoc | 206 ++++++++++++++++++ 1 file changed, 206 insertions(+) create mode 100644 sycl/doc/extensions/SPIRV/SPV_INTEL_debug_module.asciidoc diff --git a/sycl/doc/extensions/SPIRV/SPV_INTEL_debug_module.asciidoc b/sycl/doc/extensions/SPIRV/SPV_INTEL_debug_module.asciidoc new file mode 100644 index 000000000000..35012975fae5 --- /dev/null +++ b/sycl/doc/extensions/SPIRV/SPV_INTEL_debug_module.asciidoc @@ -0,0 +1,206 @@ +SPV_INTEL_debug_module +====================== + +Name Strings +------------ + +SPV_INTEL_debug_module + +Contact +------- + +To report problems with this extension, please open a new issue at: + +https://github.com/intel/llvm + +Contributors +------------ + +- Mariya Podchishchaeva, Intel +- Alexey Sotkin, Intel +- Ashbaugh, Ben, Intel + +Notice +------ + +Copyright (c) 2021 Intel Corporation. All rights reserved. + +Status +------ + +First draft + +Version +------- + +[width="40%",cols="25,25"] +|======================================== +| Last Modified Date | 2021-06-22 +| Revision | 3 +|======================================== + +Dependencies +------------ + +This extension is written against the SPIR-V Specification, +Version 1.5 Revision 5, Unified + +This extension requires SPIR-V 1.0. and OpenCL.DebugInfo.100 Extended +Instruction Set + +Overview +-------- + +This extension adds new instruction `DebugModuleINTEL` to OpenCL.DebugInfo.100 +Extended Instruction Set. This instruction allows to represent concept of a +"module" used in some programming languages. +Example - Fortran module or Clang module. The proposed instruction is defined in +accordance with LLVM `!DIModule` metadata for easier translation between +SPIR-V/LLVM. + +Extension Name +-------------- + +To use this extension within a SPIR-V module, the following +*OpExtension* must be present in the module: + +---- +OpExtension "SPV_INTEL_debug_module" +---- + +New Capabilities +---------------- +This extension introduces a new capability: + +---- +DebugInfoModuleINTEL +---- + +New Instructions +---------------- +This extension adds the following extended instruction: + +---- +DebugModuleINTEL +---- + +Token Number Assignments +------------------------ +[width="45%",cols="30,15"] +|=============================== +| DebugInfoModuleINTEL | 6114 +| DebugModuleINTEL | 36 +|=============================== + +Modifications to the SPIR-V Specification, Version 1.5, Revision, Unified +-------------------------------------------------------------------------- + +Capabilities +~~~~~~~~~~~~ + +Modify Section 3.31, "Capability", adding these rows to the Capability table: + +-- +[options="header"] +|==== +2+^| Capability ^| Implicitly Declares +| 6114 | *DebugInfoModuleINTEL* + +Allow to use `DebugModuleINTEL` extended instruction if OpenCL.DebugInfo.100 Extended Instruction Set is imported | +|==== +-- + +Modifications to the OpenCL.DebugInfo.100 Extended Instruction Set +------------------------------------------------------------------ + +Instructions +~~~~~~~~~~~ + +Modify section 4.10 "Imported Entities", adding the following instruction: + +[cols="13", width="100%"] +|===== +12+^|*DebugModuleINTEL* + + +Represents a module in the programming language, for example a Fortran module. + + +_Result Type_ must be *OpTypeVoid* + + +_Set_ must be result of an OpExtInstImport instruction. + + +_Name_ is an *OpString*, holding the name of the imported module. + + +_Source_ is a *DebugSource* instruction representing text of the source program + +of the module. + + +_Line_ is a single word literal denoting the source line number at which the + +declaration or use of a module appears in the _Source_. + + +_Parent_ is id of a debug instruction which represents the parent lexical scope. + + +_ConfigurationMacros_ is an *OpString*, holding space-separated shell-quoted + +list of -D macro definitions as they would appear on a command line specified + +to a preprocessor on early stages of _Source_ translation to a SPIR-V module. + + +_IncludePath_ is an *OpString*, holding the path to the module map file. + + +_APINotesFile_ is an *OpString*, holding the path to an API notes file for this + +module. + + +_IsDecl_ indicates if the module is a declaration and must be one of the + +following values: + +0 indicates that this module is not a declaration + +1 indicates that this module is a declaration + + +The *DebugModuleINTEL* instruction has no semantic impact and can be safely +removed from the module if all references, to the Result of this instruction are +replaced with id of *DebugInfoNone* instruction. + +Result of this instruction can be used as _Entity_ operand of +*DebugImportedEntity* instruction. + +Any non-literal operand, except _Set_, can be _id_ of *DebugInfoNone* +instruction in case the corresponding debug information is unavailable. String +operands can also refer to an *OpString*, holding an empty string in this +case. + +| Capability: +*DebugInfoModuleINTEL* + +| 13 | 12 | _ Result type_ | _Result _ | _ Set_ | _ Name_ | _ Source_ | _Literal Number Line_ | _ Parent_ | _ ConfigurationMacros_ | _ IncludePath_ | _ APINotesFile_ | _Literal IsDeclaration_ | +|===== + +Modify the description of *DebugImportedEntity* instruction by changing the +first sentence to: +Represents a C++ namespace using-directive, namespace alias, using-declaration +or imported module. + +In section 4.5. Global Variables of OpenCL.DebugInfo.100 Extended +Instruction Set specification: + +Modify the description of *DebugGlobalVariable* instruction by changing the +description of _Parent_ operand to: +Parent is a debug instruction which represents parent lexical scope. Must be one +of the following: *DebugCompilationUnit*, *DebugFunction*, *DebugLexicalBlock*, +*DebugTypeComposite* or *DebugModuleINTEL*. + +Issues +------ + +1) Any issues? + +Discussion: + +... + +Revision History +---------------- + +[cols="5,15,15,70"] +[grid="rows"] +[options="header"] +|======================================== +|Rev|Date|Author|Changes +|1|2021-06-04|Mariya Podchishchaeva|Initial revision +|2|2021-06-10|Mariya Podchishchaeva|Apply review Feedback +|3|2021-06-22|Mariya Podchishchaeva|Apply review Feedback +|======================================== From f5d93410465cb624a785ef6f1e140a175df862cd Mon Sep 17 00:00:00 2001 From: Mariya Podchishchaeva Date: Fri, 25 Jun 2021 13:04:53 +0300 Subject: [PATCH 2/4] Update sycl/doc/extensions/SPIRV/SPV_INTEL_debug_module.asciidoc Co-authored-by: Artem Gindinson --- sycl/doc/extensions/SPIRV/SPV_INTEL_debug_module.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sycl/doc/extensions/SPIRV/SPV_INTEL_debug_module.asciidoc b/sycl/doc/extensions/SPIRV/SPV_INTEL_debug_module.asciidoc index 35012975fae5..33cf5c166401 100644 --- a/sycl/doc/extensions/SPIRV/SPV_INTEL_debug_module.asciidoc +++ b/sycl/doc/extensions/SPIRV/SPV_INTEL_debug_module.asciidoc @@ -152,7 +152,7 @@ following values: + 1 indicates that this module is a declaration + The *DebugModuleINTEL* instruction has no semantic impact and can be safely -removed from the module if all references, to the Result of this instruction are +removed from the module if all references to _Result_ of this instruction are replaced with id of *DebugInfoNone* instruction. Result of this instruction can be used as _Entity_ operand of From d901a275261d7b491a369e0387c9e9e93a47b3fc Mon Sep 17 00:00:00 2001 From: Mariya Podchishchaeva Date: Fri, 25 Jun 2021 13:06:50 +0300 Subject: [PATCH 3/4] Update SPV_INTEL_debug_module.asciidoc --- sycl/doc/extensions/SPIRV/SPV_INTEL_debug_module.asciidoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/sycl/doc/extensions/SPIRV/SPV_INTEL_debug_module.asciidoc b/sycl/doc/extensions/SPIRV/SPV_INTEL_debug_module.asciidoc index 33cf5c166401..9ee301b759df 100644 --- a/sycl/doc/extensions/SPIRV/SPV_INTEL_debug_module.asciidoc +++ b/sycl/doc/extensions/SPIRV/SPV_INTEL_debug_module.asciidoc @@ -18,7 +18,7 @@ Contributors - Mariya Podchishchaeva, Intel - Alexey Sotkin, Intel -- Ashbaugh, Ben, Intel +- Ashbaugh Ben, Intel Notice ------ @@ -117,9 +117,9 @@ Instructions Modify section 4.10 "Imported Entities", adding the following instruction: -[cols="13", width="100%"] +[cols="14", width="100%"] |===== -12+^|*DebugModuleINTEL* + +13+^|*DebugModuleINTEL* + Represents a module in the programming language, for example a Fortran module. + @@ -166,7 +166,7 @@ case. | Capability: *DebugInfoModuleINTEL* -| 13 | 12 | _ Result type_ | _Result _ | _ Set_ | _ Name_ | _ Source_ | _Literal Number Line_ | _ Parent_ | _ ConfigurationMacros_ | _ IncludePath_ | _ APINotesFile_ | _Literal IsDeclaration_ | +| 13 | 12 | _ Result type_ | _Result _ | _ Set_ | 36 | _ Name_ | _ Source_ | _Literal Number Line_ | _ Parent_ | _ ConfigurationMacros_ | _ IncludePath_ | _ APINotesFile_ | _Literal IsDeclaration_ | |===== Modify the description of *DebugImportedEntity* instruction by changing the From e660a833d4b901c99e6d626c6f5cdaa823de692a Mon Sep 17 00:00:00 2001 From: Mariya Podchishchaeva Date: Tue, 29 Jun 2021 15:23:53 +0300 Subject: [PATCH 4/4] Reduce number of pluses --- .../SPIRV/SPV_INTEL_debug_module.asciidoc | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/sycl/doc/extensions/SPIRV/SPV_INTEL_debug_module.asciidoc b/sycl/doc/extensions/SPIRV/SPV_INTEL_debug_module.asciidoc index 9ee301b759df..cec6fd242a7e 100644 --- a/sycl/doc/extensions/SPIRV/SPV_INTEL_debug_module.asciidoc +++ b/sycl/doc/extensions/SPIRV/SPV_INTEL_debug_module.asciidoc @@ -129,34 +129,34 @@ _Set_ must be result of an OpExtInstImport instruction. + _Name_ is an *OpString*, holding the name of the imported module. + -_Source_ is a *DebugSource* instruction representing text of the source program + +_Source_ is a *DebugSource* instruction representing text of the source program of the module. + -_Line_ is a single word literal denoting the source line number at which the + +_Line_ is a single word literal denoting the source line number at which the declaration or use of a module appears in the _Source_. + _Parent_ is id of a debug instruction which represents the parent lexical scope. + -_ConfigurationMacros_ is an *OpString*, holding space-separated shell-quoted + -list of -D macro definitions as they would appear on a command line specified + +_ConfigurationMacros_ is an *OpString*, holding space-separated shell-quoted +list of -D macro definitions as they would appear on a command line specified to a preprocessor on early stages of _Source_ translation to a SPIR-V module. + _IncludePath_ is an *OpString*, holding the path to the module map file. + -_APINotesFile_ is an *OpString*, holding the path to an API notes file for this + +_APINotesFile_ is an *OpString*, holding the path to an API notes file for this module. + -_IsDecl_ indicates if the module is a declaration and must be one of the + +_IsDecl_ indicates if the module is a declaration and must be one of the following values: + 0 indicates that this module is not a declaration + 1 indicates that this module is a declaration + The *DebugModuleINTEL* instruction has no semantic impact and can be safely removed from the module if all references to _Result_ of this instruction are -replaced with id of *DebugInfoNone* instruction. +replaced with id of *DebugInfoNone* instruction. + Result of this instruction can be used as _Entity_ operand of -*DebugImportedEntity* instruction. +*DebugImportedEntity* instruction. + Any non-literal operand, except _Set_, can be _id_ of *DebugInfoNone* instruction in case the corresponding debug information is unavailable. String