feature: Enable Support for reading updated StateSaveHeaders

Related-To: NEO-16518

Signed-off-by: Neil R. Spruit <neil.r.spruit@intel.com>

config.h.in

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2018-2024 Intel Corporation
+ * Copyright (C) 2018-2025 Intel Corporation
  *
  * SPDX-License-Identifier: MIT
  *
@@ -9,5 +9,6 @@
 #define CONFIG_H
 
 #cmakedefine NEO_ARCH "${NEO_ARCH}"
+#cmakedefine BRANCH_TYPE @BRANCH_TYPE@
 
 #endif /* CONFIG_H */

level_zero/core/test/unit_tests/sources/device/test_l0_device.cpp

@@ -7,6 +7,7 @@
 
 #include "shared/source/command_container/implicit_scaling.h"
 #include "shared/source/command_stream/wait_status.h"
+#include "shared/source/debugger/DebuggerStateSaveHeader.h"
 #include "shared/source/helpers/api_specific_config.h"
 #include "shared/source/helpers/bit_helpers.h"
 #include "shared/source/helpers/compiler_product_helper.h"
@@ -61,7 +62,6 @@
 #include "level_zero/core/test/unit_tests/mocks/mock_memory_manager.h"
 #include "level_zero/driver_experimental/zex_common.h"
 
-#include "common/StateSaveAreaHeader.h"
 #include "gtest/gtest.h"
 
 #include <memory>

level_zero/tools/source/debug/debug_session_imp.cpp

@@ -1034,13 +1034,7 @@ void DebugSessionImp::validateAndSetStateSaveAreaHeader(uint64_t vmHandle, uint6
     if (0 == strcmp(pStateSaveArea->versionHeader.magic, "tssarea")) {
         size_t size = pStateSaveArea->versionHeader.size * 8u;
         size_t regHeaderSize = 0;
-        if (pStateSaveArea->versionHeader.version.major == 3) {
+        if (!getRegHeaderSize(pStateSaveArea, size, regHeaderSize)) {
-            DEBUG_BREAK_IF(size != sizeof(NEO::StateSaveAreaHeader));
-            regHeaderSize = sizeof(SIP::intelgt_state_save_area_V3);
-        } else if (pStateSaveArea->versionHeader.version.major < 3) {
-            DEBUG_BREAK_IF(size != sizeof(NEO::StateSaveAreaHeader::regHeader) + sizeof(NEO::StateSaveAreaHeader::versionHeader));
-            regHeaderSize = sizeof(SIP::intelgt_state_save_area);
-        } else {
             PRINT_DEBUGGER_ERROR_LOG("Setting Context State Save Area: unsupported version == %d.%d.%d\n", (int)pStateSaveArea->versionHeader.version.major, (int)pStateSaveArea->versionHeader.version.minor, (int)pStateSaveArea->versionHeader.version.patch);
             DEBUG_BREAK_IF(true);
             return;
@@ -1104,12 +1098,14 @@ const SIP::regset_desc *DebugSessionImp::getSbaRegsetDesc(L0::Device *device, co
 
     static const SIP::regset_desc sbaHeapless = {0, 0, 0, 0};
     static const SIP::regset_desc sba = {0, ZET_DEBUG_SBA_COUNT_INTEL_GPU, 64, 8};
-    if (ssah.versionHeader.version.major > 3) {
+    if (ssah.versionHeader.version.major > 5) {
         DEBUG_BREAK_IF(true);
         PRINT_DEBUGGER_ERROR_LOG("Unsupported version of State Save Area Header\n", "");
         return nullptr;
     } else if (ssah.versionHeader.version.major == 3 && isHeaplessMode(device, ssah.regHeaderV3)) {
         return &sbaHeapless;
+    } else if (ssah.versionHeader.version.major == 5) {
+        return &sbaHeapless;
     } else {
         return &sba;
     }
@@ -1522,14 +1518,14 @@ ze_result_t DebugSession::getRegisterSetProperties(Device *device, uint32_t *pCo
         ZET_DEBUG_REGSET_TYPE_DBG_INTEL_GPU,
         ZET_DEBUG_REGSET_TYPE_FC_INTEL_GPU};
 
-    // Add V3-specific register types
+    // Add V3/V5-specific register types
-    if (pStateSaveArea->versionHeader.version.major == 3) {
+    if (pStateSaveArea->versionHeader.version.major >= 3) {
         regsetTypes.insert(regsetTypes.end(), {ZET_DEBUG_REGSET_TYPE_MSG_INTEL_GPU,
                                                ZET_DEBUG_REGSET_TYPE_MODE_FLAGS_INTEL_GPU,
                                                ZET_DEBUG_REGSET_TYPE_DEBUG_SCRATCH_INTEL_GPU});
 
         // Conditionally add thread scratch for heapless mode
-        if (DebugSessionImp::isHeaplessMode(device, pStateSaveArea->regHeaderV3)) {
+        if (DebugSessionImp::isHeaplessMode(device, pStateSaveArea->regHeaderV3) || pStateSaveArea->versionHeader.version.major == 5) {
             regsetTypes.push_back(ZET_DEBUG_REGSET_TYPE_THREAD_SCRATCH_INTEL_GPU);
         }
 
@@ -1545,7 +1541,7 @@ ze_result_t DebugSession::getRegisterSetProperties(Device *device, uint32_t *pCo
     }
 
     // Handle unsupported version case
-    if (pStateSaveArea->versionHeader.version.major > 3) {
+    if (pStateSaveArea->versionHeader.version.major > 5) {
         PRINT_DEBUGGER_ERROR_LOG("Unsupported version of State Save Area Header\n", "");
         DEBUG_BREAK_IF(true);
         return ZE_RESULT_ERROR_UNKNOWN;
@@ -1606,14 +1602,8 @@ ze_result_t DebugSessionImp::registersAccessHelper(const EuThread *thread, const
 
 ze_result_t DebugSessionImp::cmdRegisterAccessHelper(const EuThread::ThreadId &threadId, SIP::sip_command &command, bool write) {
     auto stateSaveAreaHeader = getStateSaveAreaHeader();
-    const SIP::regset_desc *regdesc = nullptr;
+    SIP::regset_desc regdesc;
-    if (stateSaveAreaHeader->versionHeader.version.major == 3) {
+    if (getCommandRegisterDescriptor(stateSaveAreaHeader, &regdesc) != ZE_RESULT_SUCCESS) {
-        regdesc = &stateSaveAreaHeader->regHeaderV3.cmd;
-    } else if (stateSaveAreaHeader->versionHeader.version.major < 3) {
-        regdesc = &stateSaveAreaHeader->regHeader.cmd;
-    } else {
-        PRINT_DEBUGGER_ERROR_LOG("%s: Unsupported version of State Save Area Header\n", __func__);
-        DEBUG_BREAK_IF(true);
         return ZE_RESULT_ERROR_UNKNOWN;
     }
 
@@ -1622,7 +1612,7 @@ ze_result_t DebugSessionImp::cmdRegisterAccessHelper(const EuThread::ThreadId &t
     if (connectedDevice->getNEODevice()->getSipExternalLibInterface()) {
         type = connectedDevice->getNEODevice()->getSipExternalLibInterface()->getSipLibCommandRegisterType();
     }
-    ze_result_t result = registersAccessHelper(allThreads[threadId].get(), regdesc, 0, 1, type, &command, write);
+    ze_result_t result = registersAccessHelper(allThreads[threadId].get(), &regdesc, 0, 1, type, &command, write);
     if (result != ZE_RESULT_SUCCESS) {
         PRINT_DEBUGGER_ERROR_LOG("Failed to access CMD for thread %s\n", EuThread::toString(threadId).c_str());
     }
@@ -1788,7 +1778,7 @@ ze_result_t DebugSessionImp::readFifo(uint64_t vmHandle, std::vector<EuThread::T
     auto stateSaveAreaHeader = getStateSaveAreaHeader();
     if (!stateSaveAreaHeader) {
         return ZE_RESULT_ERROR_UNKNOWN;
-    } else if (stateSaveAreaHeader->versionHeader.version.major != 3) {
+    } else if (stateSaveAreaHeader->versionHeader.version.major < 3) {
         return ZE_RESULT_SUCCESS;
     }
 
@@ -1796,9 +1786,11 @@ ze_result_t DebugSessionImp::readFifo(uint64_t vmHandle, std::vector<EuThread::T
 
     // Drain the fifo
     uint32_t drainRetries = 2, lastHead = ~0u;
-    const uint64_t offsetTail = (sizeof(SIP::StateSaveArea)) + offsetof(struct SIP::intelgt_state_save_area_V3, fifo_tail);
+
-    const uint64_t offsetFifoSize = (sizeof(SIP::StateSaveArea)) + offsetof(struct SIP::intelgt_state_save_area_V3, fifo_size);
+    uint64_t offsetTail;
-    const uint64_t offsetFifo = gpuVa + (stateSaveAreaHeader->versionHeader.size * 8) + stateSaveAreaHeader->regHeaderV3.fifo_offset;
+    uint64_t offsetFifoSize;
+    uint64_t offsetFifo;
+    getFifoOffsets(stateSaveAreaHeader, offsetTail, offsetFifoSize, offsetFifo, gpuVa);
 
     while (drainRetries--) {
         constexpr uint32_t failsafeTimeoutWait = 50;

level_zero/tools/source/debug/debug_session_imp.h

@@ -8,13 +8,12 @@
 #pragma once
 
 #include "shared/source/built_ins/sip.h"
+#include "shared/source/debugger/DebuggerStateSaveHeader.h"
 #include "shared/source/helpers/string.h"
 
 #include "level_zero/tools/source/debug/debug_session.h"
 #include "level_zero/zet_intel_gpu_debug.h"
 
-#include "common/StateSaveAreaHeader.h"
-
 #include <atomic>
 #include <chrono>
 #include <cmath>
@@ -159,9 +158,11 @@ struct DebugSessionImp : DebugSession {
     const NEO::StateSaveAreaHeader *getStateSaveAreaHeader();
     void dumpDebugSurfaceToFile(uint64_t vmHandle, uint64_t gpuVa, const std::string &path);
     void validateAndSetStateSaveAreaHeader(uint64_t vmHandle, uint64_t gpuVa);
+    bool getRegHeaderSize(const NEO::StateSaveAreaHeader *pStateSaveArea, size_t size, size_t &regHeaderSize);
     virtual void readStateSaveAreaHeader(){};
     MOCKABLE_VIRTUAL ze_result_t readFifo(uint64_t vmHandle, std::vector<EuThread::ThreadId> &threadsWithAttention);
     MOCKABLE_VIRTUAL ze_result_t isValidNode(uint64_t vmHandle, uint64_t gpuVa, SIP::fifo_node &node);
+    void getFifoOffsets(const NEO::StateSaveAreaHeader *stateSaveAreaHeader, uint64_t &offsetTail, uint64_t &offsetFifoSize, uint64_t &offsetFifo, uint64_t gpuVa);
 
     virtual uint64_t getContextStateSaveAreaGpuVa(uint64_t memoryHandle) = 0;
     virtual size_t getContextStateSaveAreaSize(uint64_t memoryHandle) = 0;
@@ -172,6 +173,7 @@ struct DebugSessionImp : DebugSession {
     void slmSipVersionCheck();
     MOCKABLE_VIRTUAL ze_result_t cmdRegisterAccessHelper(const EuThread::ThreadId &threadId, SIP::sip_command &command, bool write);
     MOCKABLE_VIRTUAL ze_result_t waitForCmdReady(EuThread::ThreadId threadId, uint16_t retryCount);
+    ze_result_t getCommandRegisterDescriptor(const NEO::StateSaveAreaHeader *stateSaveAreaHeader, SIP::regset_desc *regdesc);
 
     uint32_t getRegisterSize(uint32_t type) override;
 

level_zero/tools/source/debug/debug_session_sip_external_lib.cpp

@@ -8,6 +8,7 @@
 #include "level_zero/tools/source/debug/debug_session_sip_external_lib.h"
 
 #include "shared/source/device/device.h"
+#include "shared/source/sip_external_lib/sip_external_lib.h"
 
 #include "level_zero/core/source/device/device.h"
 
@@ -40,4 +41,37 @@ uint32_t DebugSessionImp::getSipRegisterType(zet_debug_regset_type_intel_gpu_t z
     return static_cast<uint32_t>(zeRegisterType);
 }
 
+bool DebugSessionImp::getRegHeaderSize(const NEO::StateSaveAreaHeader *pStateSaveArea, size_t size, size_t &regHeaderSize) {
+    if (pStateSaveArea->versionHeader.version.major == 3) {
+        DEBUG_BREAK_IF(size != sizeof(NEO::StateSaveAreaHeader::regHeaderV3) + sizeof(NEO::StateSaveAreaHeader::versionHeader));
+        regHeaderSize = sizeof(SIP::intelgt_state_save_area_V3);
+        return true;
+    } else if (pStateSaveArea->versionHeader.version.major < 3) {
+        DEBUG_BREAK_IF(size != sizeof(NEO::StateSaveAreaHeader::regHeader) + sizeof(NEO::StateSaveAreaHeader::versionHeader));
+        regHeaderSize = sizeof(SIP::intelgt_state_save_area);
+        return true;
+    }
+
+    return false;
+}
+
+ze_result_t DebugSessionImp::getCommandRegisterDescriptor(const NEO::StateSaveAreaHeader *stateSaveAreaHeader, SIP::regset_desc *regdesc) {
+    if (stateSaveAreaHeader->versionHeader.version.major == 3) {
+        *regdesc = std::move(stateSaveAreaHeader->regHeaderV3.cmd);
+    } else if (stateSaveAreaHeader->versionHeader.version.major < 3) {
+        *regdesc = std::move(stateSaveAreaHeader->regHeader.cmd);
+    } else {
+        PRINT_DEBUGGER_ERROR_LOG("%s: Unsupported version of State Save Area Header\n", __func__);
+        DEBUG_BREAK_IF(true);
+        return ZE_RESULT_ERROR_UNKNOWN;
+    }
+    return ZE_RESULT_SUCCESS;
+}
+
+void DebugSessionImp::getFifoOffsets(const NEO::StateSaveAreaHeader *stateSaveAreaHeader, uint64_t &offsetTail, uint64_t &offsetFifoSize, uint64_t &offsetFifo, uint64_t gpuVa) {
+    offsetTail = (sizeof(SIP::StateSaveArea)) + offsetof(struct SIP::intelgt_state_save_area_V3, fifo_tail);
+    offsetFifoSize = (sizeof(SIP::StateSaveArea)) + offsetof(struct SIP::intelgt_state_save_area_V3, fifo_size);
+    offsetFifo = gpuVa + (stateSaveAreaHeader->versionHeader.size * 8) + stateSaveAreaHeader->regHeaderV3.fifo_offset;
+}
+
 } // namespace L0

level_zero/tools/source/debug/windows/debug_session.cpp

@@ -7,6 +7,7 @@
 
 #include "level_zero/tools/source/debug/windows/debug_session.h"
 
+#include "shared/source/debugger/DebuggerStateSaveHeader.h"
 #include "shared/source/device/device.h"
 #include "shared/source/execution_environment/root_device_environment.h"
 #include "shared/source/gmm_helper/gmm_helper.h"
@@ -17,8 +18,6 @@
 
 #include "level_zero/core/source/gfx_core_helpers/l0_gfx_core_helper.h"
 
-#include "common/StateSaveAreaHeader.h"
-
 namespace L0 {
 
 DebugSession *createDebugSessionHelper(const zet_debug_config_t &config, Device *device, int debugFd, void *params);

level_zero/tools/test/unit_tests/sources/debug/debug_session_common.h

@@ -7,6 +7,7 @@
 
 #pragma once
 
+#include "shared/source/debugger/DebuggerStateSaveHeader.h"
 #include "shared/source/debugger/debugger_l0.h"
 #include "shared/source/os_interface/os_interface.h"
 #include "shared/test/common/mocks/mock_device.h"
@@ -17,8 +18,6 @@
 #include "level_zero/core/test/unit_tests/mocks/mock_built_ins.h"
 #include "level_zero/core/test/unit_tests/mocks/mock_device.h"
 
-#include "common/StateSaveAreaHeader.h"
-
 namespace L0 {
 namespace ult {
 

level_zero/tools/test/unit_tests/sources/debug/debug_session_tests.cpp

@@ -5,6 +5,7 @@
  *
  */
 
+#include "shared/source/debugger/DebuggerStateSaveHeader.h"
 #include "shared/source/helpers/gfx_core_helper.h"
 #include "shared/source/sip_external_lib/sip_external_lib.h"
 #include "shared/test/common/libult/global_environment.h"
@@ -26,7 +27,6 @@
 #include "level_zero/tools/test/unit_tests/sources/debug/mock_debug_session.h"
 #include "level_zero/zet_intel_gpu_debug.h"
 
-#include "common/StateSaveAreaHeader.h"
 #include "encode_surface_state_args.h"
 
 #include <list>
@@ -2164,25 +2164,6 @@ TEST(DebugSessionTest, GivenSwFifoWhenStateSaveAreaVersionIsLessThanThreeDuringF
     EXPECT_EQ(ZE_RESULT_SUCCESS, session->readFifo(0, threadsWithAttention));
 }
 
-TEST(DebugSessionTest, GivenSwFifoWhenStateSaveAreaVersionIsGreaterThanThreeDuringFifoReadThenFifoIsNotReadAndSuccessIsReturned) {
-    auto stateSaveAreaHeader = MockSipData::createStateSaveAreaHeader(2);
-    reinterpret_cast<NEO::StateSaveAreaHeader *>(stateSaveAreaHeader.data())->versionHeader.version.major = 4;
-
-    zet_debug_config_t config = {};
-    config.pid = 0x1234;
-    auto hwInfo = *NEO::defaultHwInfo.get();
-    NEO::MockDevice *neoDevice(NEO::MockDevice::createWithNewExecutionEnvironment<NEO::MockDevice>(&hwInfo, 0));
-    MockDeviceImp deviceImp(neoDevice);
-    auto session = std::make_unique<MockDebugSession>(config, &deviceImp);
-
-    session->stateSaveAreaHeader.clear();
-    session->stateSaveAreaHeader.resize(stateSaveAreaHeader.size());
-    memcpy_s(session->stateSaveAreaHeader.data(), session->stateSaveAreaHeader.size(), stateSaveAreaHeader.data(), stateSaveAreaHeader.size());
-
-    std::vector<EuThread::ThreadId> threadsWithAttention;
-    EXPECT_EQ(ZE_RESULT_SUCCESS, session->readFifo(0, threadsWithAttention));
-}
-
 TEST_F(DebugSessionTestSwFifoFixture, GivenSwFifoWhenReadingSwFifoAndIsValidNodeFailsThenFifoReadReturnsError) {
     EXPECT_FALSE(session->stateSaveAreaHeader.empty());
     std::vector<EuThread::ThreadId> threadsWithAttention;
@@ -3108,7 +3089,7 @@ TEST_F(DebugSessionRegistersAccessTestV3, givenSsaHeaderVersionGreaterThan3WhenT
 }
 
 TEST_F(DebugSessionRegistersAccessTestV3, givenSsaHeaderVersionGreaterThan3WhenGetSbaRegsetDescCalledThenNullIsReturned) {
-    reinterpret_cast<NEO::StateSaveAreaHeader *>(session->stateSaveAreaHeader.data())->versionHeader.version.major = 4;
+    reinterpret_cast<NEO::StateSaveAreaHeader *>(session->stateSaveAreaHeader.data())->versionHeader.version.major = 99;
     auto pStateSaveAreaHeader = session->getStateSaveAreaHeader();
 
     EXPECT_EQ(DebugSessionImp::getSbaRegsetDesc(session->getConnectedDevice(), *pStateSaveAreaHeader), nullptr);
@@ -5394,5 +5375,172 @@ TEST_F(DebugSessionRegistersAccessTestV3, givenSipExternalLibWhenCmdRegisterAcce
     rootEnv.sipExternalLib.reset(originalSipLib);
 }
 
+// Tests for getSbaRegsetDesc function
+TEST_F(DebugSessionRegistersAccessTestV3, GivenGetSbaRegsetDescWhenVersionMajorIs3AndHeaplessModeThenReturnsHeaplessDescriptor) {
+    NEO::StateSaveAreaHeader header = {};
+    header.versionHeader.version.major = 3;
+    header.regHeaderV3.sip_flags = SIP::SIP_FLAG_HEAPLESS;
+
+    auto result = L0::DebugSessionImp::getSbaRegsetDesc(deviceImp.get(), header);
+
+    ASSERT_NE(result, nullptr);
+    EXPECT_EQ(result->num, 0u);
+    EXPECT_EQ(result->offset, 0u);
+}
+
+TEST_F(DebugSessionRegistersAccessTestV3, GivenGetSbaRegsetDescWhenVersionMajorIs3AndNotHeaplessModeThenReturnsSbaDescriptor) {
+    NEO::StateSaveAreaHeader header = {};
+    header.versionHeader.version.major = 3;
+    header.regHeaderV3.sip_flags = 0; // Not heapless
+
+    auto result = L0::DebugSessionImp::getSbaRegsetDesc(deviceImp.get(), header);
+
+    ASSERT_NE(result, nullptr);
+    EXPECT_EQ(result->num, ZET_DEBUG_SBA_COUNT_INTEL_GPU);
+    EXPECT_EQ(result->bits, 64u);
+    EXPECT_EQ(result->bytes, 8u);
+}
+
+TEST_F(DebugSessionRegistersAccessTestV3, GivenGetSbaRegsetDescWhenVersionMajorIs5ThenReturnsHeaplessDescriptor) {
+    NEO::StateSaveAreaHeader header = {};
+    header.versionHeader.version.major = 5;
+
+    auto result = L0::DebugSessionImp::getSbaRegsetDesc(deviceImp.get(), header);
+
+    ASSERT_NE(result, nullptr);
+    EXPECT_EQ(result->num, 0u);
+    EXPECT_EQ(result->offset, 0u);
+}
+
+TEST_F(DebugSessionRegistersAccessTestV3, GivenGetSbaRegsetDescWhenVersionMajorIs2ThenReturnsSbaDescriptor) {
+    NEO::StateSaveAreaHeader header = {};
+    header.versionHeader.version.major = 2;
+
+    auto result = L0::DebugSessionImp::getSbaRegsetDesc(deviceImp.get(), header);
+
+    ASSERT_NE(result, nullptr);
+    EXPECT_EQ(result->num, ZET_DEBUG_SBA_COUNT_INTEL_GPU);
+    EXPECT_EQ(result->bits, 64u);
+    EXPECT_EQ(result->bytes, 8u);
+}
+
+TEST_F(DebugSessionRegistersAccessTestV3, GivenGetSbaRegsetDescWhenVersionMajorIs6ThenReturnsNullptr) {
+    NEO::StateSaveAreaHeader header = {};
+    header.versionHeader.version.major = 6;
+
+    auto result = L0::DebugSessionImp::getSbaRegsetDesc(deviceImp.get(), header);
+
+    EXPECT_EQ(result, nullptr);
+}
+
+TEST_F(DebugSessionRegistersAccessTestV3, GivenGetSbaRegsetDescWhenVersionMajorIs7ThenReturnsNullptr) {
+    NEO::StateSaveAreaHeader header = {};
+    header.versionHeader.version.major = 7;
+
+    auto result = L0::DebugSessionImp::getSbaRegsetDesc(deviceImp.get(), header);
+
+    EXPECT_EQ(result, nullptr);
+}
+
+TEST_F(DebugSessionRegistersAccessTestV3, givenVersion3WithoutHeaplessModeWhenGetRegisterSetPropertiesCalledThenThreadScratchRegsetNotIncluded) {
+    // Test the false branch of: isHeaplessMode(device, pStateSaveArea->regHeaderV3) || version.major == 5
+    // Version 3, no heapless flag, no SIP external lib -> THREAD_SCRATCH should NOT be included
+
+    auto neoDevice = deviceImp->getNEODevice();
+    auto &rootEnv = *neoDevice->getExecutionEnvironment()->rootDeviceEnvironments[neoDevice->getRootDeviceIndex()];
+    auto originalSipLib = rootEnv.sipExternalLib.release();
+
+    // Don't set SIP external lib to ensure isHeaplessMode returns false
+    rootEnv.sipExternalLib.reset(nullptr);
+
+    uint32_t count = 0;
+    auto ret = DebugSession::getRegisterSetProperties(deviceImp.get(), &count, nullptr);
+    EXPECT_EQ(ZE_RESULT_SUCCESS, ret);
+    ASSERT_GT(count, 0u);
+
+    std::vector<zet_debug_regset_properties_t> props(count);
+    ret = DebugSession::getRegisterSetProperties(deviceImp.get(), &count, props.data());
+    EXPECT_EQ(ZE_RESULT_SUCCESS, ret);
+
+    bool threadScratchFound = false;
+    for (auto &p : props) {
+        if (p.type == ZET_DEBUG_REGSET_TYPE_THREAD_SCRATCH_INTEL_GPU) {
+            threadScratchFound = true;
+            break;
+        }
+    }
+    EXPECT_FALSE(threadScratchFound);
+
+    rootEnv.sipExternalLib.reset(originalSipLib);
+}
+
+TEST_F(DebugSessionRegistersAccessTestV3, givenVersion5WhenGetRegisterSetPropertiesCalledThenThreadScratchRegsetIncluded) {
+    // Test the true branch of the second part: version.major == 5
+    // This should include THREAD_SCRATCH regardless of heapless mode
+
+    class MockSipExternalLibForV5 : public MockSipExternalLib {
+      public:
+        int getSipKernelBinary(NEO::Device &device, NEO::SipKernelType type, std::vector<char> &retBinary, std::vector<char> &stateSaveAreaHeader) override {
+            // Create a proper StateSaveAreaHeader with version 5
+            stateSaveAreaHeader.resize(sizeof(NEO::StateSaveAreaHeader));
+            auto pHeader = reinterpret_cast<NEO::StateSaveAreaHeader *>(stateSaveAreaHeader.data());
+            pHeader->versionHeader.version.major = 5;
+            pHeader->versionHeader.version.minor = 0;
+            pHeader->versionHeader.version.patch = 0;
+            pHeader->versionHeader.size = sizeof(NEO::StateSaveAreaHeader) / 8;
+            return 0;
+        }
+        bool createRegisterDescriptorMap() override { return true; }
+        SIP::regset_desc *getRegsetDescFromMap(uint32_t type) override { return nullptr; }
+        bool getSipLibRegisterAccess(void *sipHandle, SipLibThreadId sipThreadId, uint32_t sipRegisterType, uint32_t *registerCount, uint32_t *registerStartOffset) override { return true; }
+        uint32_t getSipLibCommandRegisterType() override { return 0; }
+    };
+
+    auto neoDevice = deviceImp->getNEODevice();
+    auto &rootEnv = *neoDevice->getExecutionEnvironment()->rootDeviceEnvironments[neoDevice->getRootDeviceIndex()];
+    auto originalSipLib = rootEnv.sipExternalLib.release();
+    rootEnv.sipExternalLib.reset(new MockSipExternalLibForV5());
+
+    // Create a version 5 state save area header manually
+    NEO::StateSaveAreaHeader stateSaveAreaHeader5 = {};
+    stateSaveAreaHeader5.versionHeader.version.major = 5;
+    stateSaveAreaHeader5.versionHeader.version.minor = 0;
+    stateSaveAreaHeader5.versionHeader.version.patch = 0;
+    stateSaveAreaHeader5.versionHeader.size = sizeof(NEO::StateSaveAreaHeader) / 8;
+    memcpy(stateSaveAreaHeader5.versionHeader.magic, "tssarea", 8);
+
+    // Initialize regHeaderV3 with minimal valid data (used for V5)
+    stateSaveAreaHeader5.regHeaderV3.num_slices = 1;
+    stateSaveAreaHeader5.regHeaderV3.num_subslices_per_slice = 1;
+    stateSaveAreaHeader5.regHeaderV3.num_eus_per_subslice = 8;
+    stateSaveAreaHeader5.regHeaderV3.num_threads_per_eu = 7;
+    stateSaveAreaHeader5.regHeaderV3.grf = {0, 128, 512, 64};
+
+    auto mockBuiltins = new MockBuiltins();
+    mockBuiltins->stateSaveAreaHeader.assign(reinterpret_cast<char *>(&stateSaveAreaHeader5),
+                                             reinterpret_cast<char *>(&stateSaveAreaHeader5) + sizeof(NEO::StateSaveAreaHeader));
+    MockRootDeviceEnvironment::resetBuiltins(neoDevice->getExecutionEnvironment()->rootDeviceEnvironments[0].get(), mockBuiltins);
+
+    uint32_t count = 0;
+    auto ret = DebugSession::getRegisterSetProperties(deviceImp.get(), &count, nullptr);
+    EXPECT_EQ(ZE_RESULT_SUCCESS, ret);
+    ASSERT_GT(count, 0u);
+
+    std::vector<zet_debug_regset_properties_t> props(count);
+    ret = DebugSession::getRegisterSetProperties(deviceImp.get(), &count, props.data());
+    EXPECT_EQ(ZE_RESULT_SUCCESS, ret);
+
+    bool threadScratchFound = false;
+    for (auto &p : props) {
+        if (p.type == ZET_DEBUG_REGSET_TYPE_THREAD_SCRATCH_INTEL_GPU) {
+            threadScratchFound = true;
+            break;
+        }
+    }
+    EXPECT_TRUE(threadScratchFound);
+
+    rootEnv.sipExternalLib.reset(originalSipLib);
+}
+
 } // namespace ult
 } // namespace L0

level_zero/tools/test/unit_tests/sources/debug/linux/prelim/debug_session_fixtures_linux.h

@@ -5,6 +5,7 @@
  *
  */
 
+#include "shared/source/debugger/DebuggerStateSaveHeader.h"
 #include "shared/source/device/device.h"
 #include "shared/source/os_interface/linux/drm_debug.h"
 #include "shared/source/os_interface/linux/i915_prelim.h"
@@ -24,8 +25,6 @@
 #include "level_zero/tools/test/unit_tests/sources/debug/debug_session_common.h"
 #include "level_zero/tools/test/unit_tests/sources/debug/linux/debug_session_fixtures_linux.h"
 
-#include "common/StateSaveAreaHeader.h"
-
 #include <atomic>
 #include <queue>
 #include <type_traits>

level_zero/tools/test/unit_tests/sources/debug/linux/prelim/test_debug_api_linux.cpp

@@ -10,6 +10,7 @@
 // prevent including any other headers to avoid redefinition errors
 #define _I915_DRM_H_
 
+#include "shared/source/debugger/DebuggerStateSaveHeader.h"
 #include "shared/source/gmm_helper/gmm_helper.h"
 #include "shared/source/helpers/aligned_memory.h"
 #include "shared/source/helpers/basic_math.h"
@@ -41,8 +42,6 @@
 #include "level_zero/tools/test/unit_tests/sources/debug/mock_debug_session.h"
 #include "level_zero/zet_intel_gpu_debug.h"
 
-#include "common/StateSaveAreaHeader.h"
-
 #include <fcntl.h>
 
 namespace NEO {

level_zero/tools/test/unit_tests/sources/debug/linux/xe/debug_session_fixtures_linux_xe.h

@@ -5,6 +5,7 @@
  *
  */
 
+#include "shared/source/debugger/DebuggerStateSaveHeader.h"
 #include "shared/source/os_interface/linux/drm_debug.h"
 #include "shared/source/os_interface/linux/xe/eudebug/eudebug_interface_upstream.h"
 #include "shared/source/os_interface/os_interface.h"
@@ -24,8 +25,6 @@
 #include "level_zero/tools/test/unit_tests/sources/debug/debug_session_common.h"
 #include "level_zero/tools/test/unit_tests/sources/debug/linux/debug_session_fixtures_linux.h"
 
-#include "common/StateSaveAreaHeader.h"
-
 #include <atomic>
 #include <queue>
 #include <type_traits>

level_zero/tools/test/unit_tests/sources/debug/linux/xe/test_debug_api_linux_xe.cpp

@@ -5,6 +5,7 @@
  *
  */
 
+#include "shared/source/debugger/DebuggerStateSaveHeader.h"
 #include "shared/source/gmm_helper/gmm_helper.h"
 #include "shared/source/helpers/aligned_memory.h"
 #include "shared/source/helpers/basic_math.h"
@@ -41,8 +42,6 @@
 #include "level_zero/tools/test/unit_tests/sources/debug/mock_debug_session.h"
 #include "level_zero/zet_intel_gpu_debug.h"
 
-#include "common/StateSaveAreaHeader.h"
-
 #include <fcntl.h>
 #include <fstream>
 #include <type_traits>

level_zero/tools/test/unit_tests/sources/debug/test_debug_api.cpp

@@ -315,7 +315,7 @@ TEST_F(DebugApiTest, givenNonZeroCountAndNullRegsetPointerWhenGetRegisterSetProp
 TEST_F(DebugApiTest, givenSsaHeaderVersionGreaterThan3WhenGetRegisterSetPropertiesCalledThenUnknownIsReturned) {
     auto stateSaveAreaHeader = MockSipData::createStateSaveAreaHeader(3);
     auto versionHeader = &reinterpret_cast<SIP::StateSaveAreaHeader *>(stateSaveAreaHeader.data())->versionHeader;
-    versionHeader->version.major = 4;
+    versionHeader->version.major = 99;
     mockBuiltins->stateSaveAreaHeader = stateSaveAreaHeader;
     uint32_t count = 0;
     EXPECT_EQ(ZE_RESULT_ERROR_UNKNOWN, zetDebugGetRegisterSetProperties(device->toHandle(), &count, nullptr));

level_zero/tools/test/unit_tests/sources/debug/windows/test_debug_api_windows.cpp

@@ -6,6 +6,7 @@
  */
 
 #include "shared/source/built_ins/sip.h"
+#include "shared/source/debugger/DebuggerStateSaveHeader.h"
 #include "shared/source/os_interface/windows/wddm_allocation.h"
 #include "shared/source/os_interface/windows/wddm_debug.h"
 #include "shared/test/common/helpers/stream_capture.h"
@@ -22,8 +23,6 @@
 #include "level_zero/tools/test/unit_tests/sources/debug/debug_session_common.h"
 #include "level_zero/tools/test/unit_tests/sources/debug/mock_debug_session.h"
 
-#include "common/StateSaveAreaHeader.h"
-
 namespace L0 {
 namespace ult {
 

shared/source/built_ins/sip.cpp

@@ -9,6 +9,7 @@
 
 #include "shared/source/built_ins/built_ins.h"
 #include "shared/source/debug_settings/debug_settings_manager.h"
+#include "shared/source/debugger/DebuggerStateSaveHeader.h"
 #include "shared/source/debugger/debugger.h"
 #include "shared/source/debugger/debugger_l0.h"
 #include "shared/source/device/device.h"
@@ -27,8 +28,6 @@
 #include "shared/source/sip_external_lib/sip_external_lib.h"
 #include "shared/source/utilities/io_functions.h"
 
-#include "common/StateSaveAreaHeader.h"
-
 namespace NEO {
 
 SipClassType SipKernel::classType = SipClassType::init;

shared/source/debugger/DebuggerStateSaveHeader.h

@@ -0,0 +1,23 @@
+/*
+ * Copyright (C) 2025 Intel Corporation
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ */
+
+#pragma once
+
+#include "config.h"
+
+#include <stdint.h>
+
+#ifdef BRANCH_TYPE
+#define STRINGIFY_HELPER(x) #x
+#define STRINGIFY(x) STRINGIFY_HELPER(x)
+// clang-format off
+#define BRANCH_HEADER_PATH STRINGIFY(BRANCH_TYPE/StateSaveAreaHeaderWrapper.h)
+// clang-format on
+#include BRANCH_HEADER_PATH
+#else
+#include "StateSaveAreaHeaderWrapper.h"
+#endif

shared/source/debugger/StateSaveAreaHeaderWrapper.h

@@ -0,0 +1,24 @@
+/*
+ * Copyright (C) 2025 Intel Corporation
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ */
+
+#pragma once
+
+#include "common/StateSaveAreaHeader.h"
+
+namespace NEO {
+// NOLINTBEGIN
+struct StateSaveAreaHeader {
+    struct SIP::StateSaveArea versionHeader;
+    union {
+        struct SIP::intelgt_state_save_area regHeader;
+        struct SIP::intelgt_state_save_area_V3 regHeaderV3;
+        uint64_t totalWmtpDataSize;
+    };
+};
+
+// NOLINTEND
+} // namespace NEO

shared/source/debugger/debugger_l0.h

@@ -10,7 +10,7 @@
 #include "shared/source/helpers/non_copyable_or_moveable.h"
 #include "shared/source/memory_manager/memory_manager.h"
 
-#include "common/StateSaveAreaHeader.h"
+#include "DebuggerStateSaveHeader.h"
 
 #include <cstdint>
 #include <memory>
@@ -23,18 +23,6 @@ class GraphicsAllocation;
 class LinearStream;
 class OSInterface;
 
-// NOLINTBEGIN
-struct StateSaveAreaHeader {
-    struct SIP::StateSaveArea versionHeader;
-    union {
-        struct SIP::intelgt_state_save_area regHeader;
-        struct SIP::intelgt_state_save_area_V3 regHeaderV3;
-        uint64_t totalWmtpDataSize;
-    };
-};
-
-// NOLINTEND
-
 #pragma pack(1)
 struct SbaTrackedAddresses {
     char magic[8] = "sbaarea";

shared/test/common/helpers/sip_init.cpp

@@ -5,14 +5,13 @@
  *
  */
 
+#include "shared/source/debugger/DebuggerStateSaveHeader.h"
 #include "shared/source/debugger/debugger_l0.h"
 #include "shared/source/device/device.h"
 #include "shared/source/helpers/gfx_core_helper.h"
 #include "shared/source/memory_manager/memory_allocation.h"
 #include "shared/test/common/mocks/mock_sip.h"
 
-#include "common/StateSaveAreaHeader.h"
-
 #include <cassert>
 
 namespace NEO {
@@ -31,104 +30,99 @@ void clearUseFlags() {
     called = false;
 }
 
-std::vector<char> createStateSaveAreaHeader(uint32_t version) {
-    return createStateSaveAreaHeader(version, 128);
-}
-
-std::vector<char> createStateSaveAreaHeader(uint32_t version, uint16_t grfNum) {
-    return createStateSaveAreaHeader(version, grfNum, 1);
-}
-
 std::vector<char> createStateSaveAreaHeader(uint32_t version, uint16_t grfNum, uint16_t mmeNum) {
-    SIP::StateSaveAreaHeader stateSaveAreaHeader = {
+    SIP::StateSaveArea versionHeaderV1 = {
-        {
+        // versionHeader
-            // versionHeader
+        "tssarea", // magic
-            "tssarea", // magic
+        0,         // reserved1
-            0,         // reserved1
+        {          // version
-            {          // version
+         1,        // major
-             1,        // major
+         0,        // minor
-             0,        // minor
+         0},       // patch
-             0},       // patch
+        40,        // size
-            40,        // size
+        {0, 0, 0}, // reserved2
-            {0, 0, 0}, // reserved2
+    };
-        },
+    SIP::intelgt_state_save_area regHeaderV1 = {
-        {
+        // regHeader
-            // regHeader
+        1,                    // num_slices
-            1,                    // num_slices
+        2,                    // num_subslices_per_slice
-            2,                    // num_subslices_per_slice
+        16,                   // num_eus_per_subslice
-            16,                   // num_eus_per_subslice
+        7,                    // num_threads_per_eu
-            7,                    // num_threads_per_eu
+        0,                    // state_area_offset
-            0,                    // state_area_offset
+        6144,                 // state_save_size
-            6144,                 // state_save_size
+        0,                    // slm_area_offset
-            0,                    // slm_area_offset
+        0,                    // slm_bank_size
-            0,                    // slm_bank_size
+        0,                    // slm_bank_valid
-            0,                    // slm_bank_valid
+        4740,                 // sr_magic_offset
-            4740,                 // sr_magic_offset
+        {0, grfNum, 256, 32}, // grf
-            {0, grfNum, 256, 32}, // grf
+        {4096, 1, 256, 32},   // addr
-            {4096, 1, 256, 32},   // addr
+        {4128, 2, 32, 4},     // flag
-            {4128, 2, 32, 4},     // flag
+        {4156, 1, 32, 4},     // emask
-            {4156, 1, 32, 4},     // emask
+        {4160, 2, 128, 16},   // sr
-            {4160, 2, 128, 16},   // sr
+        {4192, 1, 128, 16},   // cr
-            {4192, 1, 128, 16},   // cr
+        {4256, 1, 96, 12},    // notification
-            {4256, 1, 96, 12},    // notification
+        {4288, 1, 128, 16},   // tdr
-            {4288, 1, 128, 16},   // tdr
+        {4320, 10, 256, 32},  // acc
-            {4320, 10, 256, 32},  // acc
+        {4320, 10, 256, 32},  // mme
-            {4320, 10, 256, 32},  // mme
+        {4672, 1, 32, 4},     // ce
-            {4672, 1, 32, 4},     // ce
+        {4704, 1, 128, 16},   // sp
-            {4704, 1, 128, 16},   // sp
+        {0, 0, 0, 0},         // cmd
-            {0, 0, 0, 0},         // cmd
+        {4640, 1, 128, 16},   // tm
-            {4640, 1, 128, 16},   // tm
+        {0, 1, 32, 4},        // fc
-            {0, 1, 32, 4},        // fc
+        {4736, 1, 32, 4},     // dbg
-            {4736, 1, 32, 4},     // dbg
+    };
-        },
+    NEO::StateSaveAreaHeader stateSaveAreaHeader = {};
+    stateSaveAreaHeader.versionHeader = versionHeaderV1;
+    stateSaveAreaHeader.regHeader = regHeaderV1;
+
+    SIP::StateSaveArea versionHeaderV2 = {
+        // versionHeader
+        "tssarea", // magic
+        0,         // reserved1
+        {          // version
+         2,        // major
+         0,        // minor
+         0},       // patch
+        44,        // size
+        {0, 0, 0}, // reserved2
     };
 
-    SIP::StateSaveAreaHeader stateSaveAreaHeader2 = {
+    SIP::intelgt_state_save_area regHeaderV2 = {
-        {
+        // regHeader
-            // versionHeader
+        1,                       // num_slices
-            "tssarea", // magic
+        1,                       // num_subslices_per_slice
-            0,         // reserved1
+        8,                       // num_eus_per_subslice
-            {          // version
+        7,                       // num_threads_per_eu
-             2,        // major
+        0,                       // state_area_offset
-             0,        // minor
+        6144,                    // state_save_size
-             0},       // patch
+        0,                       // slm_area_offset
-            44,        // size
+        0,                       // slm_bank_size
-            {0, 0, 0}, // reserved2
+        0,                       // slm_bank_valid
-        },
+        4740,                    // sr_magic_offset
-        {
+        {0, grfNum, 256, 32},    // grf
-            // regHeader
+        {4096, 1, 256, 32},      // addr
-            1,                       // num_slices
+        {4128, 2, 32, 4},        // flag
-            1,                       // num_subslices_per_slice
+        {4156, 1, 32, 4},        // emask
-            8,                       // num_eus_per_subslice
+        {4160, 2, 128, 16},      // sr
-            7,                       // num_threads_per_eu
+        {4192, 1, 128, 16},      // cr
-            0,                       // state_area_offset
+        {4256, 1, 96, 12},       // notification
-            6144,                    // state_save_size
+        {4288, 1, 128, 16},      // tdr
-            0,                       // slm_area_offset
+        {4320, 10, 256, 32},     // acc
-            0,                       // slm_bank_size
+        {4320, mmeNum, 256, 32}, // mme
-            0,                       // slm_bank_valid
+        {4672, 1, 32, 4},        // ce
-            4740,                    // sr_magic_offset
+        {4704, 1, 128, 16},      // sp
-            {0, grfNum, 256, 32},    // grf
+        {4768, 1, 128 * 8, 128}, // cmd
-            {4096, 1, 256, 32},      // addr
+        {4640, 1, 128, 16},      // tm
-            {4128, 2, 32, 4},        // flag
+        {0, 1, 32, 4},           // fc
-            {4156, 1, 32, 4},        // emask
+        {4736, 1, 32, 4},        // dbg
-            {4160, 2, 128, 16},      // sr
+        {4744, 1, 64, 8},        // ctx
-            {4192, 1, 128, 16},      // cr
+        {4752, 1, 64, 8},        // dbg_reg
-            {4256, 1, 96, 12},       // notification
-            {4288, 1, 128, 16},      // tdr
-            {4320, 10, 256, 32},     // acc
-            {4320, mmeNum, 256, 32}, // mme
-            {4672, 1, 32, 4},        // ce
-            {4704, 1, 128, 16},      // sp
-            {4768, 1, 128 * 8, 128}, // cmd
-            {4640, 1, 128, 16},      // tm
-            {0, 1, 32, 4},           // fc
-            {4736, 1, 32, 4},        // dbg
-            {4744, 1, 64, 8},        // ctx
-            {4752, 1, 64, 8},        // dbg_reg
-        },
     };
+    NEO::StateSaveAreaHeader stateSaveAreaHeader2 = {};
+    stateSaveAreaHeader2.versionHeader = versionHeaderV2;
+    stateSaveAreaHeader2.regHeader = regHeaderV2;
 
-    SIP::StateSaveArea versionHeader = {
+    SIP::StateSaveArea versionHeaderV3 = {
         // versionHeader
         "tssarea", // magic
         0,         // reserved1
@@ -180,7 +174,7 @@ std::vector<char> createStateSaveAreaHeader(uint32_t version, uint16_t grfNum, u
         {4768, 1, 64, 8},               // msg
     };
     NEO::StateSaveAreaHeader stateSaveAreaHeader3 = {};
-    stateSaveAreaHeader3.versionHeader = versionHeader;
+    stateSaveAreaHeader3.versionHeader = versionHeaderV3;
     stateSaveAreaHeader3.regHeaderV3 = regHeaderV3;
 
     NEO::StateSaveAreaHeader stateSaveAreaHeader4 = {
@@ -223,6 +217,14 @@ std::vector<char> createStateSaveAreaHeader(uint32_t version, uint16_t grfNum, u
 
     return std::vector<char>(begin, begin + sizeOfHeader);
 }
+
+std::vector<char> createStateSaveAreaHeader(uint32_t version) {
+    return createStateSaveAreaHeader(version, 128);
+}
+
+std::vector<char> createStateSaveAreaHeader(uint32_t version, uint16_t grfNum) {
+    return createStateSaveAreaHeader(version, grfNum, 1);
+}
 } // namespace MockSipData
 
 bool SipKernel::initSipKernel(SipKernelType type, Device &device) {

shared/test/common/mocks/mock_compilers.cpp

@@ -8,6 +8,7 @@
 #include "shared/test/common/mocks/mock_compilers.h"
 
 #include "shared/source/compiler_interface/compiler_options.h"
+#include "shared/source/debugger/DebuggerStateSaveHeader.h"
 #include "shared/source/helpers/hw_info.h"
 #include "shared/source/os_interface/os_inc_base.h"
 #include "shared/test/common/helpers/mock_file_io.h"
@@ -16,7 +17,6 @@
 #include "shared/test/common/mocks/mock_sip.h"
 
 #include "cif/macros/enable.h"
-#include "common/StateSaveAreaHeader.h"
 #include "ocl_igc_interface/fcl_ocl_device_ctx.h"
 #include "ocl_igc_interface/igc_ocl_device_ctx.h"
 

shared/test/common/mocks/mock_sip.cpp

@@ -7,11 +7,10 @@
 
 #include "shared/test/common/mocks/mock_sip.h"
 
+#include "shared/source/debugger/DebuggerStateSaveHeader.h"
 #include "shared/source/helpers/string.h"
 #include "shared/source/memory_manager/memory_allocation.h"
 
-#include "common/StateSaveAreaHeader.h"
-
 namespace NEO {
 
 static constexpr SIP::StateSaveAreaHeaderV3 mockSipStateSaveAreaHeaderV3 = {

shared/test/unit_test/built_ins/sip_tests.cpp

@@ -7,6 +7,7 @@
 
 #include "shared/source/built_ins/built_ins.h"
 #include "shared/source/command_stream/command_stream_receiver.h"
+#include "shared/source/debugger/DebuggerStateSaveHeader.h"
 #include "shared/source/debugger/debugger_l0.h"
 #include "shared/source/helpers/aligned_memory.h"
 #include "shared/source/helpers/gfx_core_helper.h"
@@ -32,8 +33,6 @@
 #include "shared/test/common/test_macros/hw_test.h"
 #include "shared/test/common/test_macros/test.h"
 
-#include "common/StateSaveAreaHeader.h"
-
 #include <map>
 
 using namespace NEO;