diff --git a/source/adapters/hip/context.hpp b/source/adapters/hip/context.hpp index c797d7459a..5af95753b8 100644 --- a/source/adapters/hip/context.hpp +++ b/source/adapters/hip/context.hpp @@ -19,6 +19,44 @@ typedef void (*ur_context_extended_deleter_t)(void *UserData); +/// UR context mapping to a HIP context object. +/// +/// There is no direct mapping between a HIP context and a UR context. +/// The main differences are described below: +/// +/// HIP context vs UR context +/// +/// One of the main differences between the UR API and the HIP driver API is +/// that the second modifies the state of the threads by assigning +/// \c hipCtx_t objects to threads. \c hipCtx_t objects store data associated +/// with a given device and control access to said device from the user side. +/// UR API context are objects that are passed to functions, and not bound +/// to threads. +/// +/// Since the \c ur_context_handle_t can contain multiple devices, and a \c +/// hipCtx_t refers to only a single device, the \c hipCtx_t is more tightly +/// coupled to a \c ur_device_handle_t than a \c ur_context_handle_t. In order +/// to remove some ambiguities about the different semantics of \c +/// \c ur_context_handle_t and native \c hipCtx_t, we access the native \c +/// hipCtx_t solely through the \c ur_device_handle_t class, by using the object +/// \ref ScopedContext, which sets the active device (by setting the active +/// native \c hipCtx_t). +/// +/// Primary vs User-defined \c hipCtx_t +/// +/// HIP has two different types of \c hipCtx_t, the Primary context, which is +/// usable by all threads on a given process for a given device, and the +/// aforementioned custom \c hipCtx_t s. The HIP documentation, confirmed with +/// performance analysis, suggest using the Primary context whenever possible. +/// +/// Destructor callback +/// +/// Required to implement CP023, SYCL Extended Context Destruction, +/// the UR Context can store a number of callback functions that will be +/// called upon destruction of the UR Context. +/// See proposal for details. +/// https://github.com/codeplaysoftware/standards-proposals/blob/master/extended-context-destruction/index.md +/// /// /// Destructor callback /// @@ -52,7 +90,11 @@ struct ur_context_handle_t_ { std::atomic_uint32_t RefCount; ur_context_handle_t_(const ur_device_handle_t *Devs, uint32_t NumDevices) - : Devices{Devs, Devs + NumDevices}, RefCount{1} {}; + : Devices{Devs, Devs + NumDevices}, RefCount{1} { + for (auto &Dev : Devices) { + urDeviceRetain(Dev); + } + }; ~ur_context_handle_t_() {}