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 * type: {The type of the constant.} 66 * [hidden:] ...If present, don't document the constant. Omit the following two fields. 67 * [deprecated: [{Deprecation message.}] ... This is deprecated. Compiler will issue a wrning. 68 * summary: {A one line string describing this section.} 69 * description: 70 * {Multiline description. Can include HTML. References to constants, types, 71 * and functions can be created by prefixing with a '@'.} 72 * end: 73 * 74 * Types can either be simple types, structs, or enums. They have the format: 75 * 76 * type: {The typedef name of the type.} 77 * [version: ({Starting API level} [ {Last API level that supports this.}] | UNRELEASED) 78 * [size: {32 or 64. Used if this is available only for 32 or 64 bit code.}] 79 * simple: {The C declaration that this type is the typedef equivalent.} 80 * [hidden:] ...If present, don't document the type. Omit the following two fields. 81 * [deprecated: [{Deprecation message.}] ... This is deprecated. Compiler will issue a wrning. 82 * summary: {A one line string describing this section.} 83 * description: 84 * {Multiline description. Can include HTML. References to constants, types, 85 * and functions can be created by prefixing with a '@'.} 86 * end: 87 * 88 * type: {The typedef name of the type.} 89 * [version: ({Starting API level} [ {Last API level that supports this.}] | UNRELEASED) 90 * [size: {32 or 64. Used if this is available only for 32 or 64 bit code.}] 91 * struct: [{The name that will appear right after the struct keyword}] 92 * field: {Type and name of the field}[, "{One line documentation of the field}"] 93 * field: ... Same for all the other fields of the struct. 94 * [attrib: {Attributes of the struct.}] 95 * [hidden:] ...If present, don't document the type. Omit the following two fields. 96 * summary: {A one line string describing this section.} 97 * description: 98 * {Multiline description. Can include HTML. References to constants, types, 99 * and functions can be created by prefixing with a '@'.} 100 * end: 101 * 102 * type: {The typedef name of the type.} 103 * [version: ({Starting API level} [ {Last API level that supports this.}] | UNRELEASED) 104 * [size: {32 or 64. Used if this is available only for 32 or 64 bit code.}] 105 * enum: [{The name that will appear right after the enum keyword}] 106 * value: {Type and name of the field}[, "{One line documentation of the field}"] 107 * value: ... Same for all the other values of the enum. 108 * [hidden:] ...If present, don't document the type. Omit the following two fields. 109 * summary: {A one line string describing this section.} 110 * description: 111 * {Multiline description. Can include HTML. References to constants, types, 112 * and functions can be created by prefixing with a '@'.} 113 * end: 114 115 * Functions have the following format: 116 * 117 * function: {The name of the function.} 118 * [version: ({Starting API level} [ {Last API level that supports this.}] | UNRELEASED) 119 * [size: {32 or 64. Used if this is available only for 32 or 64 bit code.}] 120 * [attrib: {Attributes of the function.}] 121 * [w: {A comma separated list of width supported. Only 1, 2, 3, 4 are supported. 122 * [t: {A comma separated list of the types supported.}]] 123 * ... Up to four w: or t: can be defined. The order matter. These will be replace 124 * ... the #1, #2, #3, #4 that can be found in the rest of the specification. 125 * ret: [{The return type} [, "{One line documentation of the return}"]] 126 * [arg:(({Type}[ {Name})]|{Elipsis})[, {ParameterEntry.testOption}][, "{One line documentation of the field}"]] 127 * [arg: ... Same for all the other arguments of the function.] 128 * [hidden:] ... If present, don't include in the HTML documentation. 129 * [deprecated: [{Deprecation message.}] ... This is deprecated. Compiler will issue a wrning. 130 * summary: {A one line string describing this section.} 131 * description: 132 * {Multiline description. Can include HTML. References to constants, types, 133 * and functions can be created by prefixing with a '@'.} 134 * [inline: 135 * {Multiline code that implements this function inline.}] 136 * [test: {How to test this function. See FunctionSpecification::mTest.}] 137 * end: 138 */ 139 140 #include <stdio.h> 141 #include <cctype> 142 #include <cstdlib> 143 #include <fstream> 144 #include <functional> 145 #include <iostream> 146 #include <memory> 147 #include <sstream> 148 #include <strings.h> 149 150 #include "Generator.h" 151 #include "Scanner.h" 152 #include "Specification.h" 153 #include "Utilities.h" 154 155 using namespace std; 156 157 static bool parseCommandLine(int argc, char* argv[], unsigned int* maxApiLevel, bool* forVerification, 158 vector<string>* specFileNames) { 159 for (int i = 1; i < argc; i++) { 160 if (argv[i][0] == '-') { 161 if (argv[i][1] == 'v') { 162 i++; 163 if (i < argc) { 164 char* end; 165 *maxApiLevel = strtol(argv[i], &end, 10); 166 if (*end != '\0') { 167 cerr << "Error. Can't parse the version number" << argv[i] << "\n"; 168 return false; 169 } 170 } else { 171 cerr << "Missing version number after -v\n"; 172 return false; 173 } 174 } else if (argv[i][1] == 'H') { 175 *forVerification = true; 176 } else { 177 cerr << "Unrecognized flag %s\n" << argv[i] << "\n"; 178 return false; 179 } 180 } else { 181 specFileNames->push_back(argv[i]); 182 } 183 } 184 if (specFileNames->size() == 0) { 185 cerr << "No spec file specified\n"; 186 return false; 187 } 188 return true; 189 } 190 191 int main(int argc, char* argv[]) { 192 // If there's no restriction, generated test files for the very highest version. 193 unsigned int maxApiLevel = VersionInfo::kUnreleasedVersion; 194 vector<string> specFileNames; 195 bool forVerification = false; 196 if (!parseCommandLine(argc, argv, &maxApiLevel, &forVerification, &specFileNames)) { 197 cout << "Usage: gen_runtime spec_file [spec_file...] [-v version_of_test_files][-H]\n"; 198 return -1; 199 } 200 bool success = true; 201 for (auto i : specFileNames) { 202 if (!systemSpecification.readSpecFile(i, maxApiLevel)) { 203 success = false; 204 } 205 } 206 if (success) { 207 success = systemSpecification.generateFiles(forVerification, maxApiLevel); 208 } 209 return success ? 0 : -2; 210 } 211