blob: 513806b8e664c1d466348efcd18536c0d60dbbab (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
|
# About guids.xml
This is the authoritive registry of unique identifers for different OA unit
hardware configurations. Userspace can reliably use these identifiers to map a
configuration to corresponding normalization equations and counter meta data.
If a hardware configuration ever changes in a backwards incompatible way
(changing the semantics and/or layout of the raw counters) then it must be
given a new GUID.
mdapi-xml-convert.py will match metric sets with a GUID from this file based on
an md5 hash of the hardware register configuration and skip a metric set with a
warning if no GUID could be found.
All new metric sets need to be allocated a GUID here before
mdapi-xml-convert.py will output anything for that
metric set. This ensures we don't automatically import new metric sets without
some explicit review that that's appropriate.
A failure to find a GUID for an older metric set most likely implies that the
register configuration was changed. It's possible that the change is benign
(e.g. a comment change) and in that case the mdapi_config_hash for the
corresponding metric set below can be updated.
The update-guids.py script is the recommended way of managing updates to this
file by generate a temporary file with proposed updates that you can compare
with the current guids.xml.
# update-guids.xml
update-guids.py can help with:
* Recognising new metrics from VPG's MDAPI XML files
*(NOTE: new guids.xml entries will initially be missing the
config_hash=MD5_HASH attribute until mdapi-xml-convert.py is used to generate
a corresponding oa-*.xml config description)*
* Adding a config_hash=MD5_HASH attribute to recently added guids.xml entries
after mdapi-xml-convert.py has been run.
* Allocating a GUID for a custom metric that doesn't have a counterpart in
VPG's MDAPI XML files.
For this case you can add a stub entry with only a name like `<guid
name="Foo">` to guids.xml and then running update-guids.py will output a
corresponding line with the addition of an id=UUID attribute.
# How to sync the oa-\*.xml files with latest internal MDAPI XML files
1. E.g. copy a new `MetricsXML_BDW.xml` to `mdapi/MetricsXML_BDW.xml`
*Note: that the `mdapi-xml-convert.py` script will only convert configs that
have a corresponding GUID entry within `guids.xml`. This check helps avoid
unintentionally publishing early, work-in-progress/pre-production configs.*
The `guids.xml` registry maps each, complex OA unit register configuration to a
unique ID that userspace can recognise and trust the semantics of raw counters
read using that configuration. (Just for reference, this is particularly
valuable for tools that capture raw metrics for later, offline processing since
the IDs effectively provide a compressed description of how to interpret the
data by providing an index into a database of high-level counter descriptions.)
The registry associates each ID with a hash of the HW register config as found in
MDAPI XML files ('mdapi_config_hash') and also with a hash of the HW config as
found in oa-\*.xml files ('config_hash'). The hashes used for lookups in the
registry also help detect when the register config for a pre-existing metric set
is updated. Note: these hashes are only for the low-level hardware configuration
so updates to counter descriptions used by fronted UIs won't affect indexing
here.
There is a chicken and egg situation when updating or adding new entries to
guids.xml since we can't hash the configs in oa-\*.xml until successfully running
mdapi-xml-convert.py which depends on a guids.xml registry entry first. The
update-guids.xml script will output registry entries without an oa-\*.xml config
hash if not available and can be re-run after mdapi-xml-convert.py to add the
missing hashes.
2. Now run:
```
./update-guids.py --guids=guids.xml mdapi/MetricsXML_BDW.xml > guids.xml2
```
*(note the script expects to find oa-\*.xml files in the current directory)*
Diff `guids.xml` and `guilds.xml2` (easiest with a side-by-side diff editor) and
review the registry changes. *Note: many lines will have a warning like `"Not
found in MDAPI XML file[s]..."` if `update-guids.xml` wasn't given all known
MDAPI XML files but in this case they can be ignored for all non-BDW configs.*
*Note: for any config that is already supported upstream in the xe_oa driver
we need to be careful if the hash for a metric set changes in case the semantics
for any raw counters were changed. The semantics of raw counters associated with
a given GUID form part of the drm xe_oa uapi contract and must remain
backwards compatible.*
If the diff shows any `mdapi_config_hash` changes for pre-existing (especially
upstream) configs you should review the MDAPI XML changes for the metric set and
verify the change just relates to a bug fix. If more substantial changes were
made which could mean we need to treat it as a new config. Handling the later
case is left as an exercise to the reader, since it hasn't happened so far :-D.
Assuming all the changes and new entries look good they can be copied into
`guids.xml`, removing any trailing comment left by `update-guids.py`.
3. Now run mdapi-xml-convert.py:
```
./mdapi-xml-convert.py --guids=guids.xml mdapi/MetricsXML_BDW.xml > oa-bdw.xml
```
4. We can now update new entries in guids.xml with a 'config_hash':
```
./update-guids.py --guids=guids.xml mdapi/MetricsXML_BDW.xml > guids.xml2
```
*(and again diff, check the changes and copy across)*
|
