Generator.cpp revision c5184e202ced435258adb2cfe2013570e7190954 
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 RS version to target the
29 * test files for.  The header file will always contain all the functions.
30 *
31 * This program contains five main classes:
32 * - SpecFile: Represents on spec file.
33 * - Function: Each instance represents a function, like clamp.  Even though the
34 *      spec file contains many entries for clamp, we'll only have one clamp instance.
35 * - FunctionSpecification: Defines one of the many variations of the function.  There's
36 *      a one to one correspondance between FunctionSpecification objects and entries in the
37 *      spec file.  Strings that are parts of a FunctionSpecification can include placeholders,
38 *      which are "#1", "#2", "#3", and "#4".  We'll replace these by values before
39 *      generating the files.
40 * - Permutation: A concrete version of a specification, where all placeholders have
41 *      been replaced by actual values.
42 * - ParameterDefinition: A definition of a parameter of a concrete function.
43 *
44 * The format of the .spec files is described below.  Line that starts with # are comments.
45 * Replace the {} sections with your own contents.  [] indicates optional parts.
46 *
47 * It should start with a header as follows:
48 *
49 * header:
50 * summary:  {A one line string describing this section.}
51 * description:
52 *     {Multiline description.  Can include HTML.  References to constants, types,
53 *      and functions can be created by prefixing with a '@'.}
54 * [include:
55 *     { Multiline code lines to be included as-is in the generated header file.}]
56 * end:
57 *
58 * Constants are defined as follows:
59 *
60 * constant:  {The name of the constant.}
61 * [version: {Starting API level} [ {Last API level that supports this.}]
62 * [size: {32 or 64.  Used if this is available only for 32 or 64 bit code.}]
63 * value: {The value of the constant.}
64 * [hidden:]   ...If present, don't document the constant.  Omit the following two fields.
65 * summary: {A one line string describing this section.}
66 * description:
67 *     {Multiline description.  Can include HTML.  References to constants, types,
68 *      and functions can be created by prefixing with a '@'.}
69 * end:
70 *
71 * Types can either be simple types, structs, or enums.  They have the format:
72 *
73 * type:  {The typedef name of the type.}
74 * [version: {Starting API level} [ {Last API level that supports this.}]
75 * [size: {32 or 64.  Used if this is available only for 32 or 64 bit code.}]
76 * simple: {The C declaration that this type is the typedef equivalent.}
77 * [hidden:]   ...If present, don't document the type.  Omit the following two fields.
78 * summary: {A one line string describing this section.}
79 * description:
80 *     {Multiline description.  Can include HTML.  References to constants, types,
81 *      and functions can be created by prefixing with a '@'.}
82 * end:
83 *
84 * type:  {The typedef name of the type.}
85 * [version: {Starting API level} [ {Last API level that supports this.}]
86 * [size: {32 or 64.  Used if this is available only for 32 or 64 bit code.}]
87 * struct: [{The name that will appear right after the struct keyword}]
88 * field: {Type and name of the field}[, "{One line documentation of the field}"]
89 * field:   ... Same for all the other fields of the struct.
90 * [attrib: {Attributes of the struct.}]
91 * [hidden:]   ...If present, don't document the type.  Omit the following two fields.
92 * summary: {A one line string describing this section.}
93 * description:
94 *     {Multiline description.  Can include HTML.  References to constants, types,
95 *      and functions can be created by prefixing with a '@'.}
96 * end:
97 *
98 * type:  {The typedef name of the type.}
99 * [version: {Starting API level} [ {Last API level that supports this.}]
100 * [size: {32 or 64.  Used if this is available only for 32 or 64 bit code.}]
101 * enum: [{The name that will appear right after the enum keyword}]
102 * value: {Type and name of the field}[, "{One line documentation of the field}"]
103 * value:   ... Same for all the other values of the enum.
104 * [hidden:]   ...If present, don't document the type.  Omit the following two fields.
105 * summary: {A one line string describing this section.}
106 * description:
107 *     {Multiline description.  Can include HTML.  References to constants, types,
108 *      and functions can be created by prefixing with a '@'.}
109 * end:
110
111 * Functions have the following format:
112 *
113 * function:  {The name of the function.}
114 * [version: {Starting API level} [ {Last API level that supports this.}]
115 * [size: {32 or 64.  Used if this is available only for 32 or 64 bit code.}]
116 * [attrib: {Attributes of the function.}]
117 * [w: {A comma separated list of width supported.  Only 1, 2, 3, 4 are supported.
118 * [t: {A comma separated list of the types supported.}]]
119 * ... Up to four w: or t: can be defined.  The order matter.  These will be replace
120 * ... the #1, #2, #3, #4 that can be found in the rest of the specification.
121 * ret: [{The return type} [, "{One line documentation of the return}"]]
122 * [arg: {Type}[, {Name}][, {ParameterEntry.testOption}][, "{One line documentation of the field}"]]
123 * [arg:   ... Same for all the other arguments of the function.]
124 * [hidden:]   ... If present, don't include in the HTML documentation.
125 * summary: {A one line string describing this section.}
126 * description:
127 *     {Multiline description.  Can include HTML.  References to constants, types,
128 *      and functions can be created by prefixing with a '@'.}
129 * [inline:
130 *     {Multiline code that implements this function inline.}]
131 * [test: {How to test this function.  See FunctionSpecification::mTest.}]
132 * end:
133 */
134
135#include <stdio.h>
136#include <cctype>
137#include <cstdlib>
138#include <fstream>
139#include <functional>
140#include <iostream>
141#include <memory>
142#include <sstream>
143#include <strings.h>
144
145#include "Generator.h"
146#include "Scanner.h"
147#include "Specification.h"
148#include "Utilities.h"
149
150using namespace std;
151
152static bool parseCommandLine(int argc, char* argv[], int* versionOfTestFiles,
153                             vector<string>* specFileNames) {
154    for (int i = 1; i < argc; i++) {
155        if (argv[i][0] == '-') {
156            if (argv[i][1] == 'v') {
157                i++;
158                if (i < argc) {
159                    char* end;
160                    *versionOfTestFiles = strtol(argv[i], &end, 10);
161                    if (*end != '\0') {
162                        cerr << "Error. Can't parse the version number" << argv[i] << "\n";
163                        return false;
164                    }
165                } else {
166                    cerr << "Missing version number after -v\n";
167                    return false;
168                }
169            } else {
170                cerr << "Unrecognized flag %s\n" << argv[i] << "\n";
171                return false;
172            }
173        } else {
174            specFileNames->push_back(argv[i]);
175        }
176    }
177    if (specFileNames->size() == 0) {
178        cerr << "No spec file specified\n";
179        return false;
180    }
181    return true;
182}
183
184int main(int argc, char* argv[]) {
185    // If there's no restriction, generated test files for the very highest version.
186    int versionOfTestFiles = 999999;
187    vector<string> specFileNames;
188    if (!parseCommandLine(argc, argv, &versionOfTestFiles, &specFileNames)) {
189        cout << "Usage: gen_runtime spec_file [spec_file...] [-v version_of_test_files]\n";
190        return -1;
191    }
192    bool success = true;
193    for (auto i : specFileNames) {
194        if (!systemSpecification.readSpecFile(i)) {
195            success = false;
196        }
197    }
198    if (success) {
199        success = systemSpecification.generateFiles(versionOfTestFiles);
200    }
201    return success ? 0 : -2;
202}
203