Joseph Macaranas
509 строки
26 KiB
C++
509 строки
26 KiB
C++
/*
|
|
***********************************************************************************************************************
|
|
*
|
|
* Copyright (c) 2014-2025 Advanced Micro Devices, Inc. All Rights Reserved.
|
|
*
|
|
* Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
* of this software and associated documentation files (the "Software"), to deal
|
|
* in the Software without restriction, including without limitation the rights
|
|
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
* copies of the Software, and to permit persons to whom the Software is
|
|
* furnished to do so, subject to the following conditions:
|
|
*
|
|
* The above copyright notice and this permission notice shall be included in all
|
|
* copies or substantial portions of the Software.
|
|
*
|
|
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
* SOFTWARE.
|
|
*
|
|
**********************************************************************************************************************/
|
|
/**
|
|
***********************************************************************************************************************
|
|
* @file palLib.h
|
|
* @brief Defines the Platform Abstraction Library (PAL) initialization and destruction functions.
|
|
***********************************************************************************************************************
|
|
*/
|
|
|
|
#pragma once
|
|
|
|
#include "pal.h"
|
|
#include "palSysMemory.h"
|
|
#include "palDbgPrint.h"
|
|
|
|
/// Major interface version. Note that the interface version is distinct from the PAL version itself, which is returned
|
|
/// in @ref Pal::PlatformProperties.
|
|
///
|
|
/// @attention Updates to the major version indicate an interface change that is not backward compatible and may require
|
|
/// action from each client during their next integration. When determining if a change is backward
|
|
/// compatible, it is assumed that the client will default-initialize all structs.
|
|
///
|
|
/// @ingroup LibInit
|
|
#define PAL_INTERFACE_MAJOR_VERSION 942
|
|
|
|
/// Minimum major interface version. This is the minimum interface version PAL supports in order to support backward
|
|
/// compatibility. When it is equal to PAL_INTERFACE_MAJOR_VERSION, only the latest interface version is supported.
|
|
///
|
|
/// @ingroup LibInit
|
|
#define PAL_MINIMUM_INTERFACE_MAJOR_VERSION 872
|
|
|
|
/// Minimum supported major interface version for devdriver library. This is the minimum interface version of the
|
|
/// devdriver library that PAL is backwards compatible to.
|
|
///
|
|
/// @ingroup LibInit
|
|
#define PAL_MINIMUM_GPUOPEN_INTERFACE_MAJOR_VERSION 38
|
|
|
|
/**
|
|
***********************************************************************************************************************
|
|
* @def PAL_INTERFACE_VERSION
|
|
* @ingroup LibInit
|
|
* @brief Current PAL interface version packed into a 32-bit unsigned integer. The low 16 bits are always zero.
|
|
* They used to contain the interface minor version and remain as a placeholder in case we add it back.
|
|
*
|
|
* @see PAL_INTERFACE_MAJOR_VERSION
|
|
*
|
|
* @hideinitializer
|
|
***********************************************************************************************************************
|
|
*/
|
|
#define PAL_INTERFACE_VERSION (PAL_INTERFACE_MAJOR_VERSION << 16)
|
|
|
|
namespace Pal
|
|
{
|
|
|
|
// Forward declarations
|
|
class IPlatform;
|
|
|
|
/// This is a list of GPUs that the NULL OS layer can compile shaders to in offline mode.
|
|
enum class NullGpuId : uint32
|
|
{
|
|
Default = 0, ///< PAL gives the client an arbitrary supported null device.
|
|
#if PAL_CLIENT_INTERFACE_MAJOR_VERSION < 888
|
|
Polaris10, ///< 8.0.3
|
|
Polaris11, ///< 8.0.3
|
|
Polaris12, ///< 8.0.3
|
|
Vega10, ///< 9.0.0
|
|
Raven, ///< 9.0.2
|
|
Vega12, ///< 9.0.4
|
|
Vega20, ///< 9.0.6
|
|
Raven2, ///< 9.0.9
|
|
Renoir, ///< 9.0.9
|
|
#endif
|
|
Navi10, ///< 10.1.0
|
|
Navi12, ///< 10.1.1
|
|
Navi14, ///< 10.1.2
|
|
Navi21, ///< 10.3.0
|
|
Navi22, ///< 10.3.1
|
|
Navi23, ///< 10.3.2
|
|
Navi24, ///< 10.3.4
|
|
Rembrandt, ///< 10.3.5
|
|
Raphael, ///< 10.3.6
|
|
Navi31, ///< 11.0.0
|
|
Navi32, ///< 11.0.1
|
|
Navi33, ///< 11.0.2
|
|
Phoenix1, ///< 11.0.3
|
|
Phoenix2, ///< 11.0.3
|
|
Strix1, ///< 11.5.0
|
|
StrixHalo, ///< 11.5.1
|
|
Krackan1, ///< 11.5.2
|
|
Navi44, ///< 12.0.0
|
|
Navi48, ///< 12.0.1
|
|
#if (PAL_CLIENT_INTERFACE_MAJOR_VERSION>= 888)
|
|
#endif
|
|
Max, ///< The maximum count of null devices.
|
|
All, ///< If you want to enumerate all null devices.
|
|
};
|
|
|
|
/// Specifies which graphics IP level (GFXIP) this device has.
|
|
enum class GfxIpLevel : uint32
|
|
{
|
|
_None = 0, ///< @internal The device does not have an GFXIP block, or its level cannot be determined
|
|
|
|
// Unfortunately for Linux clients, X.h includes a "#define None 0" macro. Clients have their choice of either
|
|
// undefing None before including this header or using _None when dealing with PAL.
|
|
#ifndef None
|
|
None = _None, ///< The device does not have an GFXIP block, or its level cannot be determined
|
|
#endif
|
|
|
|
#if PAL_CLIENT_INTERFACE_MAJOR_VERSION >= 888
|
|
GfxIp10_1, ///< GFXIP 10.1 (Navi1x)
|
|
GfxIp10_3, ///< GFXIP 10.3 (Navi2x, Rembrandt, Raphael, Mendocino)
|
|
GfxIp11_0, ///< GFXIP 11.0 (Navi3x, Phoenix)
|
|
GfxIp11_5, ///< GFXIP 11.5 (Strix)
|
|
GfxIp12, ///< GFXIP 12.0 (Navi4x)
|
|
#else // PAL_CLIENT_INTERFACE_MAJOR_VERSION >= 888
|
|
GfxIp6 = 0x1,
|
|
GfxIp7 = 0x2,
|
|
GfxIp8 = 0x3,
|
|
GfxIp8_1 = 0x4,
|
|
GfxIp9 = 0x5,
|
|
GfxIp10_1 = 0x7,
|
|
GfxIp10_3 = 0x9,
|
|
GfxIp11_0 = 0xC,
|
|
GfxIp11_5 = 0xF,
|
|
GfxIp12 = 0x11,
|
|
#endif
|
|
};
|
|
|
|
/// Specifies the hardware revision. Some AMD tools hard-code these values so we cannot change them. New ASICs should
|
|
/// be added at the end of the list and be given the next highest value.
|
|
enum class AsicRevision : uint32
|
|
{
|
|
Unknown = 0x00,
|
|
#if PAL_CLIENT_INTERFACE_MAJOR_VERSION < 888
|
|
Tahiti = 0x01,
|
|
Pitcairn = 0x02,
|
|
Capeverde = 0x03,
|
|
Oland = 0x04,
|
|
Hainan = 0x05,
|
|
Bonaire = 0x06,
|
|
Hawaii = 0x07,
|
|
HawaiiPro = 0x08,
|
|
Kalindi = 0x0A,
|
|
Godavari = 0x0B,
|
|
Spectre = 0x0C,
|
|
Spooky = 0x0D,
|
|
Carrizo = 0x0E,
|
|
Bristol = 0x0F,
|
|
Stoney = 0x10,
|
|
Iceland = 0x11,
|
|
Tonga = 0x12,
|
|
TongaPro = Tonga,
|
|
Fiji = 0x13,
|
|
Polaris10 = 0x14,
|
|
Polaris11 = 0x15,
|
|
Polaris12 = 0x16,
|
|
Vega10 = 0x18,
|
|
Vega12 = 0x19,
|
|
Vega20 = 0x1A,
|
|
Raven = 0x1B,
|
|
Raven2 = 0x1C,
|
|
Renoir = 0x1D,
|
|
#endif
|
|
Navi10 = 0x1F, ///< 10.1.0
|
|
Navi12 = 0x21, ///< 10.1.1
|
|
Navi14 = 0x23, ///< 10.1.2
|
|
Navi21 = 0x24, ///< 10.3.0
|
|
Navi22 = 0x25, ///< 10.3.1
|
|
Navi23 = 0x26, ///< 10.3.2
|
|
Navi24 = 0x27, ///< 10.3.4
|
|
Navi31 = 0x2C, ///< 11.0.0
|
|
Navi32 = 0x2D, ///< 11.0.1
|
|
Navi33 = 0x2E, ///< 11.0.2
|
|
Rembrandt = 0x2F, ///< 10.3.5
|
|
Strix1 = 0x33, ///< 11.5.0
|
|
Raphael = 0x34, ///< 10.3.6
|
|
Phoenix1 = 0x35, ///< 11.0.3
|
|
Phoenix2 = 0x38, ///< 11.0.3
|
|
HawkPoint1 = 0x39, ///< 11.0.3
|
|
HawkPoint2 = 0x3A, ///< 11.0.3
|
|
Krackan1 = 0x3B, ///< 11.5.2
|
|
StrixHalo = 0x3C, ///< 11.5.1
|
|
Navi44 = 0x3D, ///< 12.0.0
|
|
Navi48 = 0x3E, ///< 12.0.1
|
|
};
|
|
|
|
/// Maps a null GPU ID to its associated text name.
|
|
struct NullGpuInfo
|
|
{
|
|
NullGpuId nullGpuId; ///< ID of an ASIC that PAL supports for override purposes
|
|
const char* pGpuName; ///< Text name of the ASIC specified by nullGpuId
|
|
};
|
|
|
|
/// Various IDs and info associated with a particular GPU.
|
|
struct GpuInfo
|
|
{
|
|
AsicRevision asicRev; ///< PAL specific ASIC revision identifier.
|
|
NullGpuId nullId; ///< PAL specific GPU ID supported by the NULL OS layer.
|
|
GfxIpLevel gfxIpLevel; ///< PAL specific identifier for the device's graphics IP level (GFXIP).
|
|
uint32 familyId; ///< Hardware family ID. Driver-defined identifier for a particular family of devices.
|
|
uint32 eRevId; ///< GPU emulation/internal revision ID.
|
|
uint32 revisionId; ///< GPU revision. HW-specific value differentiating between different SKUs or revisions.
|
|
uint32 gfxEngineId; ///< Coarse-grain GFX engine ID (R800, SI, etc.).
|
|
uint32 deviceId; ///< PCI device ID (e.g., Hawaii XT = 0x67B0).
|
|
const char* pGpuName; ///< ASIC name and AMDGPU target name (e.g., "NAVI31:gfx1100").
|
|
};
|
|
|
|
#if PAL_CLIENT_INTERFACE_MAJOR_VERSION < 915
|
|
/// PAL client APIs.
|
|
enum class ClientApi : uint32
|
|
{
|
|
Pal = 0,
|
|
Dx9 = 1,
|
|
Dx12 = 3,
|
|
Vulkan = 4,
|
|
OpenCl = 7,
|
|
Hip = 8,
|
|
Amf = 9,
|
|
};
|
|
#else
|
|
/// The client UMD must identify its API using this enum. Some UMD builds may implement multiple APIs so they must
|
|
/// specify which API they're implementing at runtime. Note that the PAL_CLIENT macros are the preferred way to
|
|
/// implement client-specific behavior; runtime ClientApi checks should only be used when necessary.
|
|
enum class ClientApi : uint32
|
|
{
|
|
OpenCl,
|
|
Hip
|
|
};
|
|
#endif
|
|
|
|
/// Specifies properties for @ref IPlatform creation. Input structure to Pal::CreatePlatform().
|
|
struct PlatformCreateInfo
|
|
{
|
|
const Util::AllocCallbacks* pAllocCb; ///< Optional client-provided callbacks. If non-null, PAL will call the
|
|
/// specified callbacks to allocate and free all internal system
|
|
/// memory. If null, PAL will manage memory on its own through the C
|
|
/// runtime library.
|
|
const Util::LogCallbackInfo* pLogInfo; ///< Optional client-provided callback info. If non-null, Pal will
|
|
/// call the callback to pass debug prints to the client.
|
|
|
|
const char* pSettingsPath; ///< A null-terminated string describing the path to where settings are
|
|
/// located on the system. For example, on Windows, this will refer to
|
|
/// which UMD subkey to look in under a device's key. For Linux, this
|
|
/// is the path to the settings file.
|
|
|
|
union
|
|
{
|
|
struct
|
|
{
|
|
uint32 disableGpuTimeout : 1; ///< Disables GPU timeout detection (Windows only)
|
|
uint32 force32BitVaSpace : 1; ///< Forces 32bit VA space for the flat address with 32bit ISA
|
|
uint32 createNullDevice : 1; ///< Set to create a null device, so "nullGpuId" below for the
|
|
/// ID of the GPU the created device will be based on. Null
|
|
/// devices operate in IFH mode; useful for off-line shader
|
|
/// compilations.
|
|
uint32 enableSvmMode : 1; ///< Enable SVM mode. When this bit is set, PAL will reserve
|
|
/// cpu va range with size "maxSvmSize", and allow client to
|
|
/// to create gpu or pinned memory for use of Svm.
|
|
/// For detail of SVM, please refer to CreateSvmGpuMemory
|
|
uint32 requestShadowDescriptorVaRange : 1; ///< Requests that PAL provides support for the client to use
|
|
/// the @ref VaRange::ShadowDescriptorTable virtual-address
|
|
/// range. Some GPU's may not be capable of supporting this,
|
|
/// even when requested by the client.
|
|
uint32 disableInternalResidencyOpts : 1; ///< Disables residency optimizations for internal GPU memory
|
|
/// allocations. Some clients may wish to have them turned
|
|
/// off to save on system resources.
|
|
uint32 supportRgpTraces : 1; ///< Indicates that the client supports RGP tracing. PAL will
|
|
/// use this flag and the hardware support flag to setup the
|
|
/// DevDriver RgpServer.
|
|
uint32 dontOpenPrimaryNode : 1; ///< No primary node is needed (Linux only)
|
|
uint32 disableDevDriver : 1; ///< If no DevDriverMgr should be created with this Platform.
|
|
uint32 reserved : 23; ///< Reserved for future use.
|
|
};
|
|
uint32 u32All; ///< Flags packed as 32-bit uint.
|
|
} flags; ///< Platform-wide creation flags.
|
|
|
|
ClientApi clientApiId; ///< Client API ID.
|
|
NullGpuId nullGpuId; ///< ID for the null device. Ignored unless the above flags.createNullDevice bit is set.
|
|
uint16 apiMajorVer; ///< Major API version number to be used by RGP. Should be set by client based on their
|
|
/// contract with RGP.
|
|
uint16 apiMinorVer; ///< Minor API version number to be used by RGP. Should be set by client based on their
|
|
/// contract with RGP.
|
|
#if PAL_CLIENT_INTERFACE_MAJOR_VERSION >= 916
|
|
uint32 instrApiVer; /// Instrumentation specification version for API-specific SQTT instrumentation fields.
|
|
/// Should be set by client based on the SQTT instrumentation spec version being targeted.
|
|
#endif
|
|
gpusize maxSvmSize; ///< Maximum amount of virtual address space that will be reserved for SVM
|
|
};
|
|
|
|
/**
|
|
************************************************************************************************************************
|
|
* @brief Determines the amount of system memory required for a Platform object.
|
|
*
|
|
* This function must be called before any other interaction with PAL. An allocation of this amount of memory must be
|
|
* provided in the pPlacementAddr parameter of Pal::CreatePlatform.
|
|
*
|
|
* @ingroup LibInit
|
|
*
|
|
* @returns Size, in bytes, of system memory required for an IPlatform object.
|
|
************************************************************************************************************************
|
|
*/
|
|
size_t PAL_STDCALL GetPlatformSize();
|
|
|
|
/**
|
|
***********************************************************************************************************************
|
|
* @brief Creates the Platform Abstraction Library.
|
|
*
|
|
* On execution of CreatePlatform(), PAL will establish a connection for OS and KMD communication, install the specified
|
|
* system memory allocation callbacks, and initialize any global internal services. Finally, the client will be
|
|
* returned an object pointer to the instantiated platform object, which is used to query the capabilities of the
|
|
* system.
|
|
*
|
|
* @ingroup LibInit
|
|
*
|
|
* @param [in] createInfo Parameters indicating the client requirements for the platform such as allocation
|
|
callbacks or the settings path.
|
|
* @param [in] pPlacementAddr Pointer to the location where PAL should construct this object. There must be as
|
|
* much size available here as reported by calling GetPlatformSize().
|
|
* @param [out] ppPlatform Platform object pointer to the instantiated platform. Must not be null.
|
|
*
|
|
* @returns Success if the initialization completed successfully. Otherwise, one of the following error codes may be
|
|
* returned:
|
|
* + ErrorInvalidPointer will be returned if:
|
|
* - pPlatform is null.
|
|
* - pPlacementAddr is null.
|
|
* - createInfo.pAllocCb is non-null but pfnAlloc and/or pfnFree is null.
|
|
* - createInfo.pSettingsPath is null.
|
|
* + ErrorInitializationFailed will be returned if PAL is unable to open a connection to the OS.
|
|
***********************************************************************************************************************
|
|
*/
|
|
Result PAL_STDCALL CreatePlatform(
|
|
const PlatformCreateInfo& createInfo,
|
|
void* pPlacementAddr,
|
|
IPlatform** ppPlatform);
|
|
|
|
/**
|
|
***********************************************************************************************************************
|
|
* @brief Provides an association of NULL devices and their associated text name. NULL devices operate in IFH mode
|
|
* and are primarily intended for off-line shader compilation mode. The text name is provided for end-user
|
|
* identification of the GPU device being created.
|
|
*
|
|
* @param [in,out] pNullDeviceCount On input, this is the size of the "pNullDevices" array. On output, this
|
|
* reflects the number of valid entries in the "pNullDevices" array.
|
|
* @param [out] pNullDevices Includes information on the valid NULL devices supported by the system. If
|
|
* this is NULL, then pNullDeviceCount reflects the maximum possible size of the
|
|
* null-devices array.
|
|
*
|
|
* @returns Success if the initialization completed successfully. Otherwise, one of the following error codes may be
|
|
* returned:
|
|
* + ErrorInvalidPointer will be returned if either input is NULL.
|
|
***********************************************************************************************************************
|
|
*/
|
|
Result PAL_STDCALL EnumerateNullDevices(
|
|
uint32* pNullDeviceCount,
|
|
NullGpuInfo* pNullDevices);
|
|
|
|
/**
|
|
***********************************************************************************************************************
|
|
* @brief Provides the NULL device GpuInfo data for the specified NullGpuId.
|
|
*
|
|
* @param [in] nullGpuId Null GPU ID to lookup.
|
|
* @param [out] pGpuInfo GpuInfo data on successful lookup. Must not be null.
|
|
*
|
|
* @returns Success if the lookup completed successfully. Otherwise, one of the following error codes may be returned:
|
|
* + ErrorInvalidPointer will be returned if pGpuInfo is NULL.
|
|
* + NotFound will be returned if the Null GPU ID was not found.
|
|
***********************************************************************************************************************
|
|
*/
|
|
Result PAL_STDCALL GetNullGpuInfoForNullGpuId(
|
|
NullGpuId nullGpuId,
|
|
GpuInfo* pGpuInfo);
|
|
|
|
#if PAL_CLIENT_INTERFACE_MAJOR_VERSION < 933
|
|
inline Result PAL_STDCALL GetGpuInfoForNullGpuId(
|
|
NullGpuId nullGpuId,
|
|
GpuInfo* pGpuInfo)
|
|
{
|
|
return GetNullGpuInfoForNullGpuId(nullGpuId, pGpuInfo);
|
|
}
|
|
#endif
|
|
|
|
/**
|
|
***********************************************************************************************************************
|
|
* @brief Provides the NULL device GpuInfo data for the specified GPU name string.
|
|
*
|
|
* @param [in] pGpuName Name string of the GPU to lookup (e.g., "NAVI10").
|
|
* @param [out] pGpuInfo GpuInfo data on successful lookup. Must not be null.
|
|
*
|
|
* @returns Success if the lookup completed successfully. Otherwise, one of the following error codes may be returned:
|
|
* + ErrorInvalidPointer will be returned if pGpuName or pGpuInfo are NULL.
|
|
* + NotFound will be returned if the Name string was not found.
|
|
***********************************************************************************************************************
|
|
*/
|
|
Result PAL_STDCALL GetNullGpuInfoForName(
|
|
const char* pGpuName,
|
|
GpuInfo* pGpuInfo);
|
|
|
|
#if PAL_CLIENT_INTERFACE_MAJOR_VERSION < 933
|
|
inline Result PAL_STDCALL GetGpuInfoForName(
|
|
const char* pGpuName,
|
|
GpuInfo* pGpuInfo)
|
|
{
|
|
return GetNullGpuInfoForName(pGpuName, pGpuInfo);
|
|
}
|
|
#endif
|
|
|
|
/**
|
|
***********************************************************************************************************************
|
|
* @brief Provides the NULL device GpuInfo data for the specified hardware revision.
|
|
*
|
|
* @param [in] asicRevision Hardware revision to lookup.
|
|
* @param [out] pGpuInfo GpuInfo data on successful lookup. Must not be null.
|
|
*
|
|
* @returns Success if the lookup completed successfully. Otherwise, one of the following error codes may be returned:
|
|
* + ErrorInvalidPointer will be returned if pGpuInfo is NULL.
|
|
* + NotFound will be returned if the hardware revision was not found.
|
|
***********************************************************************************************************************
|
|
*/
|
|
Result PAL_STDCALL GetNullGpuInfoForAsicRevision(
|
|
AsicRevision asicRevision,
|
|
GpuInfo* pGpuInfo);
|
|
|
|
#if PAL_CLIENT_INTERFACE_MAJOR_VERSION < 933
|
|
inline Result PAL_STDCALL GetGpuInfoForAsicRevision(
|
|
AsicRevision asicRevision,
|
|
GpuInfo* pGpuInfo)
|
|
{
|
|
return GetNullGpuInfoForAsicRevision(asicRevision, pGpuInfo);
|
|
}
|
|
#endif
|
|
|
|
/**
|
|
***********************************************************************************************************************
|
|
* @defgroup LibInit Library Initialization and Destruction
|
|
*
|
|
* Before initializing PAL, it is important to make sure that the interface version is consistent with the client's
|
|
* expectations. The client should check @ref PAL_INTERFACE_MAJOR_VERSION to ensure the major interface version has not
|
|
* changed since the last PAL integration. Ideally, this should be performed with a compile-time assert comparing
|
|
* @ref PAL_INTERFACE_MAJOR_VERSION against a client-maintained expected major version. Minor interface version
|
|
* changes should be backward compatible, and do not require a client change to maintain previous levels of
|
|
* functionality.
|
|
*
|
|
* On startup, the client's first call to PAL must be GetPlatformSize() followed by CreatePlatform(). This function
|
|
* gives an opportunity for PAL to perform any necessary platform-wide initialization such as opening a connection for
|
|
* communication with the operating system and kernel mode driver or initializing tracking facilities for system memory
|
|
* management. CreatePlatform() returns a created IPlatform object for future interaction with PAL.
|
|
*
|
|
* PAL optionally allows the client to specify a set of memory management callbacks during initialization. If
|
|
* specified, PAL will not allocate or free any memory directly from the runtime, instead calling back to the client.
|
|
* The client (or application, if the client forwards on the requests) may be able to implement a more efficient
|
|
* allocation scheme.
|
|
*
|
|
* After a successful call to CreatePlatform(), the client should call @ref IPlatform::EnumerateDevices() in order to
|
|
* get a list of supported devices attached to the system. This function returns an array of @ref IDevice objects
|
|
* which are used by the client to query properties of the devicess and eventually execute work on those devices.
|
|
* IPlatform::EnumerateDevices() is not available to util-only clients (PAL_BUILD_CORE=0).
|
|
*
|
|
* The client may re-enumerate devices at any time by calling IPlatform::EnumerateDevices(). The client must make sure
|
|
* there is no active work on any device and that all objects associated with those devices have been destroyed.
|
|
* IPlatform::EnumerateDevices() will destroy all previously reported @ref IDevice objects and return a fresh set.
|
|
* The client is required to re-enumerate devices when it receives a ErrorDeviceLost error from PAL.
|
|
*
|
|
* After enumerating devices, either during start-up or when recovering from an ErrorDeviceLost error, the client must
|
|
* setup and finalize PAL's per-device settings. See IDevice::GetPublicSettings(), IDevice::SetDxRuntimeData(),
|
|
* IDevice::CommitSettingsAndInit(), and IDevice::Finalize() for details.
|
|
*
|
|
* After enumerating devices and finalizing them, the client may query the set of available screens. This is done by
|
|
* calling the @ref IPlatform::GetScreens() function. Note that screens are not available for DX clients. Each screen
|
|
* is accessible by zero or more of the enumerated devices. Most screens are accessible from a "main" device as well as
|
|
* several other devices which can perform cross-display Flip presents to the screen. In some configurations, screens
|
|
* may not be directly to any of PAL's devices, in which case fullscreen presents are unavailable to that screen. (This
|
|
* typically only occurs in PowerExpress configurations.) Note that when IPlatform::EnumerateDevices() is called, any
|
|
* enumerated @ref IScreen objects which existed prior to that call are invalidated for the specified platform and
|
|
* IPlatform::GetScreens() needs to be called again to get the updated list of screens.
|
|
*
|
|
* On shutdown, the client should call @ref IPlatform::Destroy() to allow PAL to cleanup and free any remaining
|
|
* platform-wide resources. The client must ensure this call is not made until all other created objects are idle and
|
|
* destroyed (if destroyable).
|
|
*
|
|
* When the client is asked to destroy a device it may call IDevice::Cleanup() to explicitly clean up the device. Some
|
|
* clients will find it necessary to call Cleanup(), for example, if their devices have OS handles that become invalid.
|
|
* Note that Cleanup() doesn't destroy the device; it will return to its initial state, as if it was newly enumerated.
|
|
***********************************************************************************************************************
|
|
*/
|
|
|
|
} // Pal
|