[UR][L0] Disable USM residency P2P restriction by default

Disable the "Restrict USM residency to peers with enabled P2P access"
feature by default: P2P access is now treated as enabled for all
connectable peer devices out of the box, so USM allocations are made
resident on all of them without requiring an explicit
ext_oneapi_enable_peer_access() call. When the restriction is disabled,
urUsmP2P(Enable|Disable)PeerAccessExp become no-ops that always return
success, matching the behavior of the Level Zero V1 adapter.

Add the SYCL_UR_L0_RESTRICT_USM_RESIDENCY_TO_P2P environment variable
to opt back into the restrictive behavior on demand, requiring P2P
access to be explicitly enabled for a peer before USM allocations
become resident on it, and enforcing the enable/disable state machine.

Update the tests that exercise this feature
(sycl/test-e2e/USM/P2P/p2p_usm_residency.cpp and
unified-runtime/test/adapters/level_zero/v2/memory_residency.cpp) to
set the new environment variable so they keep testing the restrictive
behavior. Document the new variable in EnvironmentVariables.md.

Signed-off-by: Lukasz Dorau <lukasz.dorau@intel.com>

Author: ldorau

sycl/doc/EnvironmentVariables.md

@@ -294,6 +294,7 @@ older hardware or when SYCL_UR_USE_LEVEL_ZERO_V2=0 is set.</span>
 | `SYCL_PI_LEVEL_ZERO_IMMEDIATE_COMMANDLISTS_EVENT_CLEANUP_THRESHOLD` | Integer | If non-negative then the threshold is set to this value. If negative, the threshold is set to INT_MAX. Whenever the number of events associated with an immediate command list exceeds this threshold, a check is made for signaled events and these events are recycled. Setting this threshold low causes events to be checked more often, which could result in unneeded events being recycled sooner. However, more frequent event status checks may cost time. The default is 1000. | Legacy |
 | `SYCL_PI_LEVEL_ZERO_USM_RESIDENT` | Integer | Bit-mask controls if/where to make USM allocations resident at the time of allocation. Input value is of the form 0xHSD, where 4-bits of D control device allocations, 4-bits of S control shared allocations, and 4-bits of H control host allocations. Each 4-bit component is holding one of the following values: "0" - then no special residency is forced, "1" - then allocation is made resident at the device of allocation, or "2" - then allocation is made resident on all devices in the context of allocation that have P2P access to the device of allocation. Default is 0x002, i.e. force full residency for device allocations only. | Legacy |
 | `SYCL_PI_LEVEL_ZERO_USE_NATIVE_USM_MEMCPY2D` | Integer | When set to a positive value enables the use of Level Zero USM 2D memory copy operations. Default is 0. | Legacy |
+| `SYCL_UR_L0_RESTRICT_USM_RESIDENCY_TO_P2P` | Any(\*) | By default, USM device allocations are made resident on all peer devices and `ext_oneapi_enable_peer_access`/`ext_oneapi_disable_peer_access` are no-ops. Setting this variable restricts USM allocation residency to only those peer devices that have had P2P access explicitly enabled via `ext_oneapi_enable_peer_access`, requiring it to be enabled before an allocation is made resident on a peer and allowing it to be disabled again. | V2 |
 
 `(*) Note: Any means this environment variable is effective when set to any non-null value.`
 

sycl/test-e2e/USM/P2P/p2p_usm_residency.cpp

@@ -29,7 +29,7 @@
 // UNSUPPORTED-INTENDED: Test is specific to the Level Zero v2 adapter.
 //
 // RUN: %{build} -o %t.out
-// RUN: env UR_LOADER_USE_LEVEL_ZERO_V2=1 %{run} %t.out
+// RUN: %if level_zero %{env UR_LOADER_USE_LEVEL_ZERO_V2=1 SYCL_UR_L0_RESTRICT_USM_RESIDENCY_TO_P2P=1 %{run} %t.out %}
 
 #include <iostream>
 #include <vector>

unified-runtime/source/adapters/level_zero/common/device.hpp

@@ -23,6 +23,7 @@
 #include "common/ur_ref_count.hpp"
 #include "helpers/shared_helpers.hpp"
 #include "interfaces.hpp"
+#include "ur_util.hpp"
 #include <unified-runtime/ur_ddi.h>
 #include <ur/ur.hpp>
 #include <ze_api.h>
@@ -35,6 +36,20 @@ typedef size_t DeviceId;
 struct ur_device_handle_t_;
 typedef struct ur_device_handle_t_ *ur_device_handle_t;
 
+// Controls whether USM device memory residency on peer devices is restricted
+// to peers with explicitly enabled P2P access (see
+// urUsmP2P(Enable|Disable)PeerAccessExp). This is disabled by default, which
+// means P2P access is treated as enabled for all connectable peers and USM
+// allocations are made resident on all of them. Set
+// SYCL_UR_L0_RESTRICT_USM_RESIDENCY_TO_P2P=1 to opt into the restrictive
+// behavior, requiring P2P access to be explicitly enabled for a peer before
+// USM allocations become resident on it.
+inline bool restrictUsmResidencyToP2P() {
+  static const bool RestrictUsmResidencyToP2P =
+      getenv_tobool("SYCL_UR_L0_RESTRICT_USM_RESIDENCY_TO_P2P", false);
+  return RestrictUsmResidencyToP2P;
+}
+
 enum EventsScope {
   // All events are created host-visible.
   AllHostVisible,

unified-runtime/source/adapters/level_zero/common/platform.cpp

@@ -1115,9 +1115,22 @@ ur_result_t ur_platform_handle_t_::populateDeviceCacheIfNeeded() {
         continue;
       }
 
-      UR_LOG(INFO, "p2p access to memory of dev:{} from dev:{} can be enabled",
-             peerId, dev->Id.value());
-      dev->peers[peerId] = ur_device_handle_t_::PeerStatus::DISABLED;
+      // By default (i.e. unless SYCL_UR_L0_RESTRICT_USM_RESIDENCY_TO_P2P is
+      // set), P2P access is treated as enabled for all connectable peers, so
+      // that USM allocations are made resident on all of them without
+      // requiring the user to call urUsmP2PEnablePeerAccessExp explicitly.
+      if (restrictUsmResidencyToP2P()) {
+        UR_LOG(INFO,
+               "p2p access to memory of dev:{} from dev:{} can be enabled",
+               peerId, dev->Id.value());
+        dev->peers[peerId] = ur_device_handle_t_::PeerStatus::DISABLED;
+      } else {
+        UR_LOG(INFO,
+               "p2p access to memory of dev:{} from dev:{} is enabled by "
+               "default",
+               peerId, dev->Id.value());
+        dev->peers[peerId] = ur_device_handle_t_::PeerStatus::ENABLED;
+      }
     }
   }
 

unified-runtime/source/adapters/level_zero/v2/usm_p2p.cpp

@@ -48,6 +48,20 @@ static ur_result_t urUsmP2PChangePeerAccessExp(ur_device_handle_t commandDevice,
   UR_LOG(INFO, "user tries to {} peer access to memory of {} from {}",
          (isAdding ? "enable" : "disable"), *peerDevice, *commandDevice);
 
+  if (!restrictUsmResidencyToP2P()) {
+    // The restrictive P2P/residency feature is disabled (the default), so
+    // P2P access is always considered enabled for connectable peers and USM
+    // allocations are always resident on all of them. Ignore the requested
+    // state change and report success, matching the behavior of the Level
+    // Zero V1 adapter.
+    UR_LOG(INFO,
+           "ignored {} peer access to memory of {} from {}, because P2P is "
+           "always enabled unless SYCL_UR_L0_RESTRICT_USM_RESIDENCY_TO_P2P is "
+           "set",
+           (isAdding ? "enabling" : "disabling"), *peerDevice, *commandDevice);
+    return UR_RESULT_SUCCESS;
+  }
+
   {
     const auto expectedPeerStatus =
         isAdding ? ur_device_handle_t_::PeerStatus::DISABLED

unified-runtime/test/adapters/level_zero/v2/memory_residency.cpp

@@ -3,7 +3,7 @@
 //
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 
-// RUN: %with-v2 ZES_ENABLE_SYSMAN=1 ./memory_residency-test
+// RUN: %with-v2 ZES_ENABLE_SYSMAN=1 SYCL_UR_L0_RESTRICT_USM_RESIDENCY_TO_P2P=1 ./memory_residency-test
 // REQUIRES: v2
 
 #include "uur/fixtures.h"