README.md
1# Tuning Fork Validation tool
2
3This tool validates Tuning Fork proto and settings files in an APK.
4
5## tuningfork_settings
6
7The APK must contain *assets/tuningfork/tuningfork_settings.bin* file with
8serialized data for `Settings` proto message:
9
10```proto
11message Settings {
12 message Histogram {
13 optional int32 instrument_key = 1;
14 optional float bucket_min = 2;
15 optional float bucket_max = 3;
16 optional int32 n_buckets = 4;
17 }
18 message AggregationStrategy {
19 enum Submission {
20 TIME_BASED = 1;
21 TICK_BASED = 2;
22 }
23 optional Submission method = 1;
24 optional int32 intervalms_or_count = 2;
25 optional int32 max_instrumentation_keys = 3;
26 repeated int32 annotation_enum_size = 4;
27 }
28 optional AggregationStrategy aggregation_strategy = 1;
29 repeated Histogram histograms = 2;
30}
31```
32
33### Settings validation
34
35* At least one histogram
36* `max_instrumentation_keys` must be between 1 and 256
37* `annotation_enum_size` must match `Annotation` message (see below)
38
39### Example
40Example of data before serialization:
41
42```textproto
43aggregation_strategy:
44{
45 method: TIME_BASED,
46 intervalms_or_count: 600000,
47 max_instrumentation_keys: 2,
48 annotation_enum_size: [3, 4]
49}
50histograms:
51[
52 {
53 instrument_key: 0,
54 bucket_min: 28,
55 bucket_max: 32,
56 n_buckets: 70
57 },
58 {
59 instrument_key: 1,
60 bucket_min: 28,
61 bucket_max: 32,
62 n_buckets: 70
63 }
64]
65```
66
67## dev_tuningfork.proto
68
69Apk must contain *assets/tuningfork/dev_tuningfork.proto* file with `Annotation`
70and `FidelityParams` proto message.
71
72### Validation
73
74Both messages (`Annotation` and `FidelityParams`) must follow these rules
75* No oneofs
76* No Nested types
77* No extensions
78
79Additional limitation for `Annotation` message only
80* Only `ENUM` types
81* Size of enums must match 'annotation_enum_size` field in settings.
82
83Additional limitation for `FidelityParams` messsage only
84* Only `ENUM`, `FLOAT` and `INT32` types
85
86### Example
87
88Valid .proto file:
89
90```proto
91syntax = "proto3";
92
93package com.google.tuningfork;
94
95enum LoadingState {
96 UNKNOWN = 0;
97 LOADING = 1;
98 NOT_LOADING = 2;
99}
100
101enum Level {
102 UNKNOWN = 0;
103 Level_1 = 1;
104 Level_2 = 2;
105 Level_3 = 3;
106}
107
108message Annotation {
109 LoadingState loading_state = 1;
110 Level level = 2;
111}
112
113enum QualitySettings {
114 UNKNOWN = 0;
115 FASTEST = 1;
116 FAST = 2;
117 SIMPLE = 3;
118 GOOD = 4;
119 BEAUTIFUL = 5;
120 FANTASTIC = 6;
121}
122
123message FidelityParams {
124 QualitySettings quality_settings = 1;
125 int32 lod_level = 2;
126 float distance = 3;
127}
128```
129
130### Annotation size explanation
131
132*annotation_enum_size* from Settings proto must match 'Annotation' message
133
134From `Annotation` message example above:
135 * number of enum fields for `LoadingState` enum is 3
136 * number of enum fields for `Level` enum is 4
137 * `Annotation` message contains two fields - 'loading_state' and 'level'
138 * `annotation_enum_size` must be [3, 4]
139
140## dev_tuningfork_fidelityparams
141
142The APK must contain at least one file in assets/tuningfork folder with pattern
143*dev_tuningfork_fidelityparams_.{1,15}.bin*. Each file contains serialized
144parameters for `FidelityParams` proto message from *dev_tuningfork.proto* file.
145
146
147