Support SPIR-V deferred linking option (#6500)

The new option "SkipDownstreamLinking" will defer final downstream IR
linking to the user application. This option only has an effect if
there are modules that were precompiled to the target IR using
precompileForTarget().

Until now, the default behavior for SPIR-V was to use deferred linking, and
the default behavior for DXIL was to use immediate/internal linking in Slang.

This change only affects the SPIR-V behavior such that both deferred and
non-deferred linking is supported based on the new option.

To support the non-deferred option, Slang will internally call into
SPIRV-Tools-link to reconstitute a complete SPIR-V shader program when
necessary (due to modules having been precompiled to target IR).
Otherwise, if SkipDownstreamLinking is enabled, the shader returned by
e.g. getTargetCode() or getEntryPointCode() may have import linkage to
the SPIR-V embedded in the constituent modules.

Closes #4994

Co-authored-by: slangbot <186143334+slangbot@users.noreply.github.com>

6 files changed, 94 insertions, 21 deletions

diff --git a/tools/gfx-unit-test/gfx-test-util.cpp b/tools/gfx-unit-test/gfx-test-util.cpp
index 2bbe65416..d7cfa0f65 100644
--- a/tools/gfx-unit-test/gfx-test-util.cpp
+++ b/tools/gfx-unit-test/gfx-test-util.cpp
@@ -80,7 +80,8 @@ Slang::Result loadComputeProgram(
     Slang::ComPtr<gfx::IShaderProgram>& outShaderProgram,
     const char* shaderModuleName,
     const char* entryPointName,
-    slang::ProgramLayout*& slangReflection)
+    slang::ProgramLayout*& slangReflection,
+    PrecompilationMode precompilationMode)
 {
     Slang::ComPtr<slang::IBlob> diagnosticsBlob;
     slang::IModule* module = slangSession->loadModule(shaderModuleName, diagnosticsBlob.writeRef());
@@ -115,6 +116,14 @@ Slang::Result loadComputeProgram(
 
     gfx::IShaderProgram::Desc programDesc = {};
     programDesc.slangGlobalScope = composedProgram.get();
+    if (precompilationMode == PrecompilationMode::ExternalLink)
+    {
+        programDesc.downstreamLinkMode = gfx::IShaderProgram::DownstreamLinkMode::Deferred;
+    }
+    else
+    {
+        programDesc.downstreamLinkMode = gfx::IShaderProgram::DownstreamLinkMode::None;
+    }
 
     auto shaderProgram = device->createProgram(programDesc);
 
diff --git a/tools/gfx-unit-test/gfx-test-util.h b/tools/gfx-unit-test/gfx-test-util.h
index 558670162..3397584fc 100644
--- a/tools/gfx-unit-test/gfx-test-util.h
+++ b/tools/gfx-unit-test/gfx-test-util.h
@@ -7,6 +7,13 @@
 
 namespace gfx_test
 {
+enum class PrecompilationMode
+{
+    None,
+    SlangIR,
+    InternalLink,
+    ExternalLink,
+};
 /// Helper function for print out diagnostic messages output by Slang compiler.
 void diagnoseIfNeeded(slang::IBlob* diagnosticsBlob);
 
@@ -24,7 +31,8 @@ Slang::Result loadComputeProgram(
     Slang::ComPtr<gfx::IShaderProgram>& outShaderProgram,
     const char* shaderModuleName,
     const char* entryPointName,
-    slang::ProgramLayout*& slangReflection);
+    slang::ProgramLayout*& slangReflection,
+    PrecompilationMode precompilationMode = PrecompilationMode::None);
 
 Slang::Result loadComputeProgramFromSource(
     gfx::IDevice* device,
diff --git a/tools/gfx-unit-test/precompiled-module-2.cpp b/tools/gfx-unit-test/precompiled-module-2.cpp
index ca9f8b565..792f328b0 100644
--- a/tools/gfx-unit-test/precompiled-module-2.cpp
+++ b/tools/gfx-unit-test/precompiled-module-2.cpp
@@ -17,7 +17,7 @@ static Slang::Result precompileProgram(
     gfx::IDevice* device,
     ISlangMutableFileSystem* fileSys,
     const char* shaderModuleName,
-    bool precompileToTarget)
+    PrecompilationMode precompilationMode)
 {
     Slang::ComPtr<slang::ISession> slangSession;
     SLANG_RETURN_ON_FAIL(device->getSlangSession(slangSession.writeRef()));
@@ -37,7 +37,8 @@ static Slang::Result precompileProgram(
     if (!module)
         return SLANG_FAIL;
 
-    if (precompileToTarget)
+    if (precompilationMode == PrecompilationMode::InternalLink ||
+        precompilationMode == PrecompilationMode::ExternalLink)
     {
         SlangCompileTarget target;
         switch (device->getDeviceInfo().deviceType)
@@ -82,7 +83,7 @@ static Slang::Result precompileProgram(
 void precompiledModule2TestImplCommon(
     IDevice* device,
     UnitTestContext* context,
-    bool precompileToTarget)
+    PrecompilationMode precompilationMode)
 {
     Slang::ComPtr<ITransientResourceHeap> transientHeap;
     ITransientResourceHeap::Desc transientHeapDesc = {};
@@ -100,7 +101,7 @@ void precompiledModule2TestImplCommon(
         device,
         memoryFileSystem.get(),
         "precompiled-module-imported",
-        precompileToTarget));
+        precompilationMode));
 
     // Next, load the precompiled slang program.
     Slang::ComPtr<slang::ISession> slangSession;
@@ -121,6 +122,17 @@ void precompiledModule2TestImplCommon(
     }
     sessionDesc.targets = &targetDesc;
     sessionDesc.fileSystem = memoryFileSystem.get();
+
+    Slang::List<slang::CompilerOptionEntry> options;
+    slang::CompilerOptionEntry skipDownstreamLinkingOption;
+    skipDownstreamLinkingOption.name = slang::CompilerOptionName::SkipDownstreamLinking;
+    skipDownstreamLinkingOption.value.kind = slang::CompilerOptionValueKind::Int;
+    skipDownstreamLinkingOption.value.intValue0 =
+        precompilationMode == PrecompilationMode::ExternalLink;
+    options.add(skipDownstreamLinkingOption);
+
+    sessionDesc.compilerOptionEntries = options.getBuffer();
+    sessionDesc.compilerOptionEntryCount = options.getCount();
     auto globalSession = slangSession->getGlobalSession();
     globalSession->createSession(sessionDesc, slangSession.writeRef());
 
@@ -147,7 +159,8 @@ void precompiledModule2TestImplCommon(
         shaderProgram,
         "precompiled-module",
         "computeMain",
-        slangReflection));
+        slangReflection,
+        precompilationMode));
 
     ComputePipelineStateDesc pipelineDesc = {};
     pipelineDesc.program = shaderProgram.get();
@@ -208,12 +221,17 @@ void precompiledModule2TestImplCommon(
 
 void precompiledModule2TestImpl(IDevice* device, UnitTestContext* context)
 {
-    precompiledModule2TestImplCommon(device, context, false);
+    precompiledModule2TestImplCommon(device, context, PrecompilationMode::SlangIR);
+}
+
+void precompiledTargetModule2InternalLinkTestImpl(IDevice* device, UnitTestContext* context)
+{
+    precompiledModule2TestImplCommon(device, context, PrecompilationMode::InternalLink);
 }
 
-void precompiledTargetModule2TestImpl(IDevice* device, UnitTestContext* context)
+void precompiledTargetModule2ExternalLinkTestImpl(IDevice* device, UnitTestContext* context)
 {
-    precompiledModule2TestImplCommon(device, context, true);
+    precompiledModule2TestImplCommon(device, context, PrecompilationMode::ExternalLink);
 }
 
 SLANG_UNIT_TEST(precompiledModule2D3D12)
@@ -221,19 +239,42 @@ SLANG_UNIT_TEST(precompiledModule2D3D12)
     runTestImpl(precompiledModule2TestImpl, unitTestContext, Slang::RenderApiFlag::D3D12);
 }
 
-SLANG_UNIT_TEST(precompiledTargetModule2D3D12)
+SLANG_UNIT_TEST(precompiledTargetModuleInternalLink2D3D12)
 {
-    runTestImpl(precompiledTargetModule2TestImpl, unitTestContext, Slang::RenderApiFlag::D3D12);
+    runTestImpl(
+        precompiledTargetModule2InternalLinkTestImpl,
+        unitTestContext,
+        Slang::RenderApiFlag::D3D12);
 }
 
+/*
+// Unavailable on D3D12/DXIL currently
+SLANG_UNIT_TEST(precompiledTargetModuleExternalLink2D3D12)
+{
+    runTestImpl(precompiledTargetModule2ExternalLinkTestImpl, unitTestContext,
+Slang::RenderApiFlag::D3D12);
+}
+*/
+
 SLANG_UNIT_TEST(precompiledModule2Vulkan)
 {
     runTestImpl(precompiledModule2TestImpl, unitTestContext, Slang::RenderApiFlag::Vulkan);
 }
 
-SLANG_UNIT_TEST(precompiledTargetModule2Vulkan)
+SLANG_UNIT_TEST(precompiledTargetModule2InternalLinkVulkan)
+{
+    runTestImpl(
+        precompiledTargetModule2InternalLinkTestImpl,
+        unitTestContext,
+        Slang::RenderApiFlag::Vulkan);
+}
+
+SLANG_UNIT_TEST(precompiledTargetModule2ExternalLinkVulkan)
 {
-    runTestImpl(precompiledTargetModule2TestImpl, unitTestContext, Slang::RenderApiFlag::Vulkan);
+    runTestImpl(
+        precompiledTargetModule2ExternalLinkTestImpl,
+        unitTestContext,
+        Slang::RenderApiFlag::Vulkan);
 }
 
 } // namespace gfx_test
diff --git a/tools/gfx/renderer-shared.cpp b/tools/gfx/renderer-shared.cpp
index ae4ea3eef..edd271ecb 100644
--- a/tools/gfx/renderer-shared.cpp
+++ b/tools/gfx/renderer-shared.cpp
@@ -1133,11 +1133,13 @@ Result ShaderProgramBase::compileShaders(RendererBase* device)
             kernelCodes.add(downstreamIR);
         }
 
-        // If target precompilation was used, kernelCode may only represent the
-        // glue code holding together the bits of precompiled target IR.
-        // Collect those dependency target IRs too.
+        // If target precompilation with deferred downstream linking is enabled,
+        // kernelCode may only represent the glue code holding together the
+        // bits of precompiled target IR. It's the application's job to pull it
+        // together. Collect those dependency target IRs too.
         ComPtr<slang::IModulePrecompileService_Experimental> componentPrecompileService;
-        if (entryPointComponent->queryInterface(
+        if (this->desc.downstreamLinkMode == DownstreamLinkMode::Deferred &&
+            entryPointComponent->queryInterface(
                 slang::IModulePrecompileService_Experimental::getTypeGuid(),
                 (void**)componentPrecompileService.writeRef()) == SLANG_OK)
         {
diff --git a/tools/gfx/vulkan/vk-device.h b/tools/gfx/vulkan/vk-device.h
index 27cc4c3ce..06e19ad7e 100644
--- a/tools/gfx/vulkan/vk-device.h
+++ b/tools/gfx/vulkan/vk-device.h
@@ -223,6 +223,9 @@ public:
     VkSampler m_defaultSampler;
 
     RefPtr<FramebufferImpl> m_emptyFramebuffer;
+
+    // If true, slang will skip downstream linking, so we need to do it ourselves
+    bool m_skipsDownstreamLinking = false;
 };
 
 } // namespace vk
diff --git a/tools/gfx/vulkan/vk-shader-program.cpp b/tools/gfx/vulkan/vk-shader-program.cpp
index 1627c95a7..2dd9b0326 100644
--- a/tools/gfx/vulkan/vk-shader-program.cpp
+++ b/tools/gfx/vulkan/vk-shader-program.cpp
@@ -74,10 +74,20 @@ Result ShaderProgramImpl::createShaderModule(
     slang::EntryPointReflection* entryPointInfo,
     List<ComPtr<ISlangBlob>>& kernelCodes)
 {
-    ComPtr<ISlangBlob> linkedKernel = m_device->m_glslang.linkSPIRV(kernelCodes);
-    if (!linkedKernel)
+    ComPtr<ISlangBlob> linkedKernel;
+    ComPtr<slang::ISession> slangSession;
+    m_device->getSlangSession(slangSession.writeRef());
+    if (kernelCodes.getCount() == 1)
     {
-        return SLANG_FAIL;
+        linkedKernel = kernelCodes[0];
+    }
+    else
+    {
+        linkedKernel = m_device->m_glslang.linkSPIRV(kernelCodes);
+        if (!linkedKernel)
+        {
+            return SLANG_FAIL;
+        }
     }
 
     m_codeBlobs.add(linkedKernel);