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