// Copyright 2021-2024 The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

include::{generated}/meta/{refprefix}VK_KHR_global_priority.adoc[]

=== Other Extension Metadata

*Last Modified Date*::
    2021-10-22
*Contributors*::
  - Tobias Hector, AMD
  - Contributors to `apiext:VK_EXT_global_priority`
  - Contributors to `apiext:VK_EXT_global_priority_query`

=== Description

In Vulkan, users can specify device-scope queue priorities.
In some cases it may be useful to extend this concept to a system-wide
scope.
This device extension allows applications to query the global queue
priorities supported by a queue family, and then set a priority when
creating queues.
The default queue priority is ename:VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_EXT.

Implementations can report which global priority levels are treated
differently by the implementation.
It is intended primarily for use in system integration along with certain
platform-specific priority enforcement rules.

The driver implementation will attempt to skew hardware resource allocation
in favour of the higher-priority task.
Therefore, higher-priority work may retain similar latency and throughput
characteristics even if the system is congested with lower priority work.

The global priority level of a queue shall take precedence over the
per-process queue priority
(sname:VkDeviceQueueCreateInfo::pname:pQueuePriorities).

Abuse of this feature may result in starving the rest of the system from
hardware resources.
Therefore, the driver implementation may deny requests to acquire a priority
above the default priority (ename:VK_QUEUE_GLOBAL_PRIORITY_MEDIUM_EXT) if
the caller does not have sufficient privileges.
In this scenario ename:VK_ERROR_NOT_PERMITTED_EXT is returned.

The driver implementation may fail the queue allocation request if resources
required to complete the operation have been exhausted (either by the same
process or a different process).
In this scenario ename:VK_ERROR_INITIALIZATION_FAILED is returned.

include::{generated}/interfaces/VK_KHR_global_priority.adoc[]

=== Issues

1) Can we additionally query whether a caller is permitted to acquire a
specific global queue priority in this extension?

*RESOLVED*: No.
Whether a caller has enough privilege goes with the OS, and the Vulkan
driver cannot really guarantee that the privilege will not change in between
this query and the actual queue creation call.

2) If more than 1 queue using global priority is requested, is there a good
way to know which queue is failing the device creation?

*RESOLVED*: No.
There is not a good way at this moment, and it is also not quite actionable
for the applications to know that because the information may not be
accurate.
Queue creation can fail because of runtime constraints like insufficient
privilege or lack of resource, and the failure is not necessarily tied to
that particular queue configuration requested.

=== Version History

  * Revision 1, 2021-10-22 (Tobias Hector)
  ** Initial draft
