GpaOpenContext

语法

GpaStatus GpaOpenContext(
    void* context,
    GpaOpenContextFlags flags,
    GpaContextId* context_id);

描述

打开指定的上下文，该上下文提供对 GPU 性能计数器的访问。此函数必须在调用 GpaInitialize 之后以及调用任何其他 GPUPerfAPI 函数之前调用。

所提供的 context 的类型取决于使用的 API。有关传递给 GpaOpenContext 的必需类型的详细信息，请参阅下表。

API	GpaOpenContext context 参数类型
Vulkan	GpaVkContextOpenInfo*

Linux: GLXContext |

参数

名称	描述
上下文	要打开计数器的上下文。此参数的具体类型取决于 GPUPerfAPI 使用的 API。有关要使用的具体类型，请参阅上表。
flags	用于初始化上下文的标志。这应该是 GpaOpenContext 的组合。
context_id	成功执行此函数后，此参数将设置为 GPA 生成的唯一上下文标识符。此值随后可以传递给需要 GpaContextId 作为输入参数的任何 GPA 函数。

返回值

返回值	描述
kGpaStatusOk	已成功打开上下文。
kGpaStatusErrorGpaNotInitialized	GPA 未初始化。请在所有其他入口点之前调用 GpaInitialize。
kGpaStatusErrorNullPointer	提供的 pContext 参数为 NULL。
kGpaStatusErrorInvalidParameter	flags 参数的值无效。
kGpaStatusErrorHardwareNotSupported	不支持当前的 GPU 硬件。
kGpaStatusErrorDriverNotSupported	不支持当前安装的 GPU 驱动程序。
kGpaStatusErrorContextAlreadyOpen	提供的上下文已打开。
kGpaStatusErrorFailed	无法打开上下文。
kGpaStatusErrorException	发生异常。

关于 GPU 时钟模式的说明

为了在合理的功耗范围内运行，现代 GPU 会采用动态改变时钟频率的技术。这会使得性能调优变得困难，因为无法假设单一的时钟频率。默认情况下，GPA 使用一种称为“性能分析时钟”的时钟模式。在此模式下，时钟频率将被固定在可能低于正常工作频率的值。此模式应有助于确保应用程序不同运行结果之间的一致性。然而，应用程序的观测性能（特别是使用 GPUTime 计数器时）可能低于预期，或者低于应用程序在正常运行期间可以达到的性能。通过在调用 GpaOpenContext 时使用 flags 参数，您可以改变性能分析期间使用的 GPU 时钟频率。下表解释了可通过 flags 参数指定的稳定时钟模式。

时钟模式	描述
kGpaOpenContextDefaultBit

关于原始硬件计数器的说明

默认情况下，GPA 会公开一组从一个或多个原始硬件计数器计算得出的派生计数器。GPA 还可以配置为直接公开原始硬件计数器。要实现此目的，调用 GpaOpenContext 时指定的 flags 参数应包含 kGpaOpenContextEnableHardwareCountersBit 位。