1  include::meta//VK_EXT_calibrated_timestamps.txt[]
  2  
  3  *Last Modified Date*::
  4      2018-10-04
  5  *IP Status*::
  6      No known IP claims.
  7  *Contributors*::
  8    - Matthaeus G. Chajdas, AMD
  9    - Alan Harrison, AMD
 10    - Derrick Owens, AMD
 11    - Daniel Rakos, AMD
 12    - Jason Ekstrand, Intel
 13    - Keith Packard, Valve
 14  
 15  This extension provides an interface to query calibrated timestamps obtained
 16  quasi simultaneously from two time domains.
 17  
 18  === New Object Types
 19  
 20  None.
 21  
 22  === New Enum Constants
 23  
 24    * Extending elink:VkStructureType:
 25    ** ename:VK_STRUCTURE_TYPE_CALIBRATED_TIMESTAMP_INFO_EXT
 26  
 27  === New Enums
 28  
 29    * elink:VkTimeDomainEXT
 30  
 31  === New Structures
 32  
 33    * slink:VkCalibratedTimestampInfoEXT
 34  
 35  === New Functions
 36  
 37    * flink:vkGetPhysicalDeviceCalibrateableTimeDomainsEXT
 38    * flink:vkGetCalibratedTimestampsEXT
 39  
 40  === Issues
 41  
 42  1) Is the device timestamp value returned in the same time domain as the
 43  timestamp values written by flink:vkCmdWriteTimestamp?
 44  
 45  *RESOLVED*: Yes.
 46  
 47  2) What time domain is the host timestamp returned in?
 48  
 49  *RESOLVED*: A query is provided to determine the calibrateable time domains.
 50  The expected host time domain used on Windows is that of
 51  QueryPerformanceCounter, and on Linux that of CLOCK_MONOTONIC.
 52  
 53  3) Should we support other time domain combinations than just one host and
 54  the device time domain?
 55  
 56  *RESOLVED*: Supporting that would need the application to query the set of
 57  supported time domains, while supporting only one host and the device time
 58  domain would only need a query for the host time domain type.
 59  The proposed API chooses the general approach for the sake of extensibility.
 60  
 61  4) Shouldn't we use CLOCK_MONOTONIC_RAW instead of CLOCK_MONOTONIC?
 62  
 63  *RESOLVED*: CLOCK_MONOTONIC is usable in a wider set of situations, however,
 64  it is subject to NTP adjustments so some use cases may prefer
 65  CLOCK_MONOTONIC_RAW.
 66  Thus this extension allows both to be exposed.
 67  
 68  5) How can the application extrapolate future device timestamp values from
 69  the calibrated timestamp value?
 70  
 71  *RESOLVED*: slink:VkPhysicalDeviceLimits::pname:timestampPeriod makes it
 72  possible to calculate future device timestamps as follows:
 73  
 74  [source,c]
 75  ---------------------------------------------------
 76  futureTimestamp = calibratedTimestamp + deltaNanoseconds / timestampPeriod
 77  ---------------------------------------------------
 78  
 79  6) Can the host and device timestamp values drift apart over longer periods
 80  of time?
 81  
 82  *RESOLVED*: Yes, especially as some time domains by definition allow for
 83  that to happen (e.g. CLOCK_MONOTONIC is subject to NTP adjustments).
 84  Thus it's recommended that applications re-calibrate from time to time.
 85  
 86  7) Should we add a query for reporting the maximum deviation of the
 87  timestamp values returned by calibrated timestamp queries?
 88  
 89  *RESOLVED*: A global query seems inappropriate and difficult to enforce.
 90  However, it's possible to return the maximum deviation any single calibrated
 91  timestamp query can have by sampling one of the time domains twice as
 92  follows:
 93  
 94  [source,c]
 95  ---------------------------------------------------
 96  timestampX = timestampX_before = SampleTimeDomain(X)
 97  for each time domain Y != X
 98      timestampY = SampleTimeDomain(Y)
 99  timestampX_after = SampleTimeDomain(X)
100  maxDeviation = timestampX_after - timestampX_before
101  ---------------------------------------------------
102  
103  8) Can the maximum deviation reported ever be zero?
104  
105  *RESOLVED*: Unless the tick of each clock corresponding to the set of time
106  domains coincides and all clocks can literally be sampled simutaneously,
107  there isn't really a possibility for the maximum deviation to be zero, so by
108  convention the maximum deviation is always at least the maximum of the
109  length of the ticks of the set of time domains calibrated and thus can never
110  be zero.
111  
112  === Version History
113  
114    * Revision 1, 2018-10-04 (Daniel Rakos)
115      - Internal revisions.