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