1 /*
2 * Copyright (C) 2013 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 /* This program processes Renderscript function definitions described in spec files.
18 * For each spec file provided on the command line, it generates a corresponding
19 * Renderscript header (*.rsh) which is meant for inclusion in client scripts.
20 *
21 * This program also generates Junit test files to automatically test each of the
22 * functions using randomly generated data. We create two files for each function:
23 * - a Renderscript file named Test{Function}.rs,
24 * - a Junit file named Test{function}.java, which calls the above RS file.
25 *
26 * Finally, this program generates HTML documentation files.
27 *
28 * This program takes an optional -v parameter, the API level to target. The generated
29 * files will not contain APIs passed that API level. Note that this does not affect
30 * generic comments found in headers.
31 *
32 * This program contains five main classes:
33 * - SpecFile: Represents on spec file.
34 * - Function: Each instance represents a function, like clamp. Even though the
35 * spec file contains many entries for clamp, we'll only have one clamp instance.
36 * - FunctionSpecification: Defines one of the many variations of the function. There's
37 * a one to one correspondance between FunctionSpecification objects and entries in the
38 * spec file. Strings that are parts of a FunctionSpecification can include placeholders,
39 * which are "#1", "#2", "#3", and "#4". We'll replace these by values before
40 * generating the files.
41 * - Permutation: A concrete version of a specification, where all placeholders have
42 * been replaced by actual values.
43 * - ParameterDefinition: A definition of a parameter of a concrete function.
44 *
45 * The format of the .spec files is described below. Line that starts with # are comments.
46 * Replace the {} sections with your own contents. [] indicates optional parts.
47 *
48 * It should start with a header as follows:
49 *
50 * header:
51 * summary: {A one line string describing this section.}
52 * description:
53 * {Multiline description. Can include HTML. References to constants, types,
54 * and functions can be created by prefixing with a '@'.}
55 * [include:
56 * { Multiline code lines to be included as-is in the generated header file.}]
57 * end:
58 *
59 * Constants are defined as follows:
60 *
61 * constant: {The name of the constant.}
62 * [version: ({Starting API level} [ {Last API level that supports this.}] | UNRELEASED)
63 * [size: {32 or 64. Used if this is available only for 32 or 64 bit code.}]
64 * value: {The value of the constant.}
65 * [hidden:] ...If present, don't document the constant. Omit the following two fields.
66 * [deprecated: [{Deprecation message.}] ... This is deprecated. Compiler will issue a wrning.
67 * summary: {A one line string describing this section.}
68 * description:
69 * {Multiline description. Can include HTML. References to constants, types,
70 * and functions can be created by prefixing with a '@'.}
71 * end:
72 *
73 * Types can either be simple types, structs, or enums. They have the format:
74 *
75 * type: {The typedef name of the type.}
76 * [version: ({Starting API level} [ {Last API level that supports this.}] | UNRELEASED)
77 * [size: {32 or 64. Used if this is available only for 32 or 64 bit code.}]
78 * simple: {The C declaration that this type is the typedef equivalent.}
79 * [hidden:] ...If present, don't document the type. Omit the following two fields.
80 * [deprecated: [{Deprecation message.}] ... This is deprecated. Compiler will issue a wrning.
81 * summary: {A one line string describing this section.}
82 * description:
83 * {Multiline description. Can include HTML. References to constants, types,
84 * and functions can be created by prefixing with a '@'.}
85 * end:
86 *
87 * type: {The typedef name of the type.}
88 * [version: ({Starting API level} [ {Last API level that supports this.}] | UNRELEASED)
89 * [size: {32 or 64. Used if this is available only for 32 or 64 bit code.}]
90 * struct: [{The name that will appear right after the struct keyword}]
91 * field: {Type and name of the field}[, "{One line documentation of the field}"]
92 * field: ... Same for all the other fields of the struct.
93 * [attrib: {Attributes of the struct.}]
94 * [hidden:] ...If present, don't document the type. Omit the following two fields.
95 * summary: {A one line string describing this section.}
96 * description:
97 * {Multiline description. Can include HTML. References to constants, types,
98 * and functions can be created by prefixing with a '@'.}
99 * end:
100 *
101 * type: {The typedef name of the type.}
102 * [version: ({Starting API level} [ {Last API level that supports this.}] | UNRELEASED)
103 * [size: {32 or 64. Used if this is available only for 32 or 64 bit code.}]
104 * enum: [{The name that will appear right after the enum keyword}]
105 * value: {Type and name of the field}[, "{One line documentation of the field}"]
106 * value: ... Same for all the other values of the enum.
107 * [hidden:] ...If present, don't document the type. Omit the following two fields.
108 * summary: {A one line string describing this section.}
109 * description:
110 * {Multiline description. Can include HTML. References to constants, types,
111 * and functions can be created by prefixing with a '@'.}
112 * end:
113
114 * Functions have the following format:
115 *
116 * function: {The name of the function.}
117 * [version: ({Starting API level} [ {Last API level that supports this.}] | UNRELEASED)
118 * [size: {32 or 64. Used if this is available only for 32 or 64 bit code.}]
119 * [attrib: {Attributes of the function.}]
120 * [w: {A comma separated list of width supported. Only 1, 2, 3, 4 are supported.
121 * [t: {A comma separated list of the types supported.}]]
122 * ... Up to four w: or t: can be defined. The order matter. These will be replace
123 * ... the #1, #2, #3, #4 that can be found in the rest of the specification.
124 * ret: [{The return type} [, "{One line documentation of the return}"]]
125 * [arg:(({Type}[ {Name})]|{Elipsis})[, {ParameterEntry.testOption}][, "{One line documentation of the field}"]]
126 * [arg: ... Same for all the other arguments of the function.]
127 * [hidden:] ... If present, don't include in the HTML documentation.
128 * [deprecated: [{Deprecation message.}] ... This is deprecated. Compiler will issue a wrning.
129 * summary: {A one line string describing this section.}
130 * description:
131 * {Multiline description. Can include HTML. References to constants, types,
132 * and functions can be created by prefixing with a '@'.}
133 * [inline:
134 * {Multiline code that implements this function inline.}]
135 * [test: {How to test this function. See FunctionSpecification::mTest.}]
136 * end:
137 */
138
139 #include <stdio.h>
140 #include <cctype>
141 #include <cstdlib>
142 #include <fstream>
143 #include <functional>
144 #include <iostream>
145 #include <memory>
146 #include <sstream>
147 #include <strings.h>
148
149 #include "Generator.h"
150 #include "Scanner.h"
151 #include "Specification.h"
152 #include "Utilities.h"
153
154 using namespace std;
155
parseCommandLine(int argc,char * argv[],unsigned int * maxApiLevel,bool * forVerification,vector<string> * specFileNames)156 static bool parseCommandLine(int argc, char* argv[], unsigned int* maxApiLevel, bool* forVerification,
157 vector<string>* specFileNames) {
158 for (int i = 1; i < argc; i++) {
159 if (argv[i][0] == '-') {
160 if (argv[i][1] == 'v') {
161 i++;
162 if (i < argc) {
163 char* end;
164 *maxApiLevel = strtol(argv[i], &end, 10);
165 if (*end != '\0') {
166 cerr << "Error. Can't parse the version number" << argv[i] << "\n";
167 return false;
168 }
169 } else {
170 cerr << "Missing version number after -v\n";
171 return false;
172 }
173 } else if (argv[i][1] == 'H') {
174 *forVerification = true;
175 } else {
176 cerr << "Unrecognized flag %s\n" << argv[i] << "\n";
177 return false;
178 }
179 } else {
180 specFileNames->push_back(argv[i]);
181 }
182 }
183 if (specFileNames->size() == 0) {
184 cerr << "No spec file specified\n";
185 return false;
186 }
187 return true;
188 }
189
main(int argc,char * argv[])190 int main(int argc, char* argv[]) {
191 // If there's no restriction, generated test files for the very highest version.
192 unsigned int maxApiLevel = VersionInfo::kUnreleasedVersion;
193 vector<string> specFileNames;
194 bool forVerification = false;
195 if (!parseCommandLine(argc, argv, &maxApiLevel, &forVerification, &specFileNames)) {
196 cout << "Usage: gen_runtime spec_file [spec_file...] [-v version_of_test_files][-H]\n";
197 return -1;
198 }
199 bool success = true;
200 for (auto i : specFileNames) {
201 if (!systemSpecification.readSpecFile(i, maxApiLevel)) {
202 success = false;
203 }
204 }
205 if (success) {
206 success = systemSpecification.generateFiles(forVerification, maxApiLevel);
207 }
208 return success ? 0 : -2;
209 }
210