Specification.h revision 2217eb7b12e598e5b435a732207647918c171560
1/*
2 * Copyright (C) 2015 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#ifndef ANDROID_RS_API_GENERATOR_SPECIFICATION_H
18#define ANDROID_RS_API_GENERATOR_SPECIFICATION_H
19
20// See Generator.cpp for documentation of the .spec file format.
21
22#include <fstream>
23#include <list>
24#include <map>
25#include <string>
26#include <vector>
27
28class Constant;
29class ConstantSpecification;
30class Function;
31class FunctionPermutation;
32class FunctionSpecification;
33class SpecFile;
34class Specification;
35class Scanner;
36class SystemSpecification;
37class Type;
38class TypeSpecification;
39
40enum NumberKind { SIGNED_INTEGER, UNSIGNED_INTEGER, FLOATING_POINT };
41
42// Table of type equivalences.
43struct NumericalType {
44    const char* specType;    // Name found in the .spec file
45    const char* rsDataType;  // RS data type
46    const char* cType;       // Type in a C file
47    const char* javaType;    // Type in a Java file
48    NumberKind kind;
49    /* For integers, number of bits of the number, excluding the sign bit.
50     * For floats, number of implied bits of the mantissa.
51     */
52    int significantBits;
53    // For floats, number of bits of the exponent.  0 for integer types.
54    int exponentBits;
55};
56
57/* Corresponds to one parameter line in a .spec file.  These will be parsed when
58 * we instantiate the FunctionPermutation(s) that correspond to one FunctionSpecification.
59 */
60struct ParameterEntry {
61    std::string type;
62    std::string name;
63    /* Optional information on how to generate test values for this parameter.  Can be:
64     * - range(low, high): Generates values between these two limits only.
65     * - above(other_parameter): The values must be greater than those of the named parameter.
66     *       Used for clamp.
67     * - compatible(type): The values must also be fully representable in the specified type.
68     * - conditional: Don't verify this value the function return NaN.
69     */
70    std::string testOption;
71    std::string documentation;
72    int lineNumber;
73};
74
75/* Information about a parameter to a function.  The values of all the fields should only be set by
76 * parseParameterDefinition.
77 */
78struct ParameterDefinition {
79    std::string rsType;        // The Renderscript type, e.g. "uint3"
80    std::string rsBaseType;    // As above but without the number, e.g. "uint"
81    std::string javaBaseType;  // The type we need to declare in Java, e.g. "unsigned int"
82    std::string specType;      // The type found in the spec, e.g. "f16"
83    bool isFloatType;          // True if it's a floating point value
84    /* The number of entries in the vector.  It should be either "1", "2", "3", or "4".  It's also
85     * "1" for scalars.
86     */
87    std::string mVectorSize;
88    /* The space the vector takes in an array.  It's the same as the vector size, except for size
89     * "3", where the width is "4".
90     */
91    std::string vectorWidth;
92
93    std::string specName;       // e.g. x, as found in the spec file
94    std::string variableName;   // e.g. inX, used both in .rs and .java
95    std::string rsAllocName;    // e.g. gAllocInX
96    std::string javaAllocName;  // e.g. inX
97    std::string javaArrayName;  // e.g. arrayInX
98
99    // If non empty, the mininum and maximum values to be used when generating the test data.
100    std::string minValue;
101    std::string maxValue;
102    /* If non empty, contains the name of another parameter that should be smaller or equal to this
103     * parameter, i.e.  value(smallerParameter) <= value(this).  This is used when testing clamp.
104     */
105    std::string smallerParameter;
106
107    bool isOutParameter;       // True if this parameter returns data from the script.
108    bool undefinedIfOutIsNan;  // If true, we don't validate if 'out' is NaN.
109
110    int typeIndex;            // Index in the TYPES array. Negative if not found in the array.
111    int compatibleTypeIndex;  // Index in TYPES for which the test data must also fit.
112
113    /* Fill this object from the type, name, and testOption.
114     * isReturn is true if we're processing the "return:"
115     */
116    void parseParameterDefinition(const std::string& type, const std::string& name,
117                                  const std::string& testOption, int lineNumber, bool isReturn,
118                                  Scanner* scanner);
119};
120
121struct VersionInfo {
122    /* The range of versions a specification applies to. Zero if there's no restriction,
123     * so an API that became available at 12 and is still valid would have min:12 max:0.
124     * If non zero, both versions should be at least 9, the API level that introduced
125     * RenderScript.
126     */
127    int minVersion;
128    int maxVersion;
129    // Either 0, 32 or 64.  If 0, this definition is valid for both 32 and 64 bits.
130    int intSize;
131
132    VersionInfo() : minVersion(0), maxVersion(0), intSize(0) {}
133    /* Scan the version info from the spec file.  maxApiLevel specifies the maximum level
134     * we are interested in.  This may alter maxVersion.  This method returns false if the
135     * minVersion is greater than the maxApiLevel.
136     */
137    bool scan(Scanner* scanner, int maxApiLevel);
138};
139
140// We have three type of definitions
141class Definition {
142protected:
143    std::string mName;
144    bool mDeprecated;                       // True if this API should not be used
145    std::string mDeprecatedMessage;         // Optional specific warning if the API is deprecated
146    bool mHidden;                           // True if it should not be documented
147    std::string mSummary;                   // A one-line description
148    std::vector<std::string> mDescription;  // The comments to be included in the header
149    std::string mUrl;                       // The URL of the detailed documentation
150
151public:
152    Definition(const std::string& name);
153
154    std::string getName() const { return mName; }
155    bool deprecated() const { return mDeprecated; }
156    std::string getDeprecatedMessage() const { return mDeprecatedMessage; }
157    bool hidden() const { return mHidden; }
158    std::string getSummary() const { return mSummary; }
159    const std::vector<std::string>& getDescription() const { return mDescription; }
160    std::string getUrl() const { return mUrl; }
161
162    void scanDocumentationTags(Scanner* scanner, bool firstOccurence, const SpecFile* specFile);
163};
164
165/* Represents a constant, like M_PI.  This is a grouping of the version specific specifications.
166 * We'll only have one instance of Constant for each name.
167 */
168class Constant : public Definition {
169private:
170    std::vector<ConstantSpecification*> mSpecifications;  // Owned
171
172public:
173    Constant(const std::string& name) : Definition(name) {}
174    ~Constant();
175
176    const std::vector<ConstantSpecification*> getSpecifications() const { return mSpecifications; }
177    // This method should only be called by the scanning code.
178    void addSpecification(ConstantSpecification* spec) { mSpecifications.push_back(spec); }
179};
180
181/* Represents a type, like "float4".  This is a grouping of the version specific specifications.
182 * We'll only have one instance of Type for each name.
183 */
184class Type : public Definition {
185private:
186    std::vector<TypeSpecification*> mSpecifications;  // Owned
187
188public:
189    Type(const std::string& name) : Definition(name) {}
190    ~Type();
191
192    const std::vector<TypeSpecification*> getSpecifications() const { return mSpecifications; }
193    // This method should only be called by the scanning code.
194    void addSpecification(TypeSpecification* spec) { mSpecifications.push_back(spec); }
195};
196
197/* Represents a function, like "clamp".  Even though the spec file contains many entries for clamp,
198 * we'll only have one clamp instance.
199 */
200class Function : public Definition {
201private:
202    // mName in the base class contains the lower case name, e.g. native_log
203    std::string mCapitalizedName;  // The capitalized name, e.g. NativeLog
204
205    // The unique parameters between all the specifications.  NOT OWNED.
206    std::vector<ParameterEntry*> mParameters;
207    std::string mReturnDocumentation;
208
209    std::vector<FunctionSpecification*> mSpecifications;  // Owned
210
211public:
212    Function(const std::string& name);
213    ~Function();
214
215    std::string getCapitalizedName() const { return mCapitalizedName; }
216    const std::vector<ParameterEntry*>& getParameters() const { return mParameters; }
217    std::string getReturnDocumentation() const { return mReturnDocumentation; }
218    const std::vector<FunctionSpecification*> getSpecifications() const { return mSpecifications; }
219
220    bool someParametersAreDocumented() const;
221
222    // The following methods should only be called by the scanning code.
223    void addParameter(ParameterEntry* entry, Scanner* scanner);
224    void addReturn(ParameterEntry* entry, Scanner* scanner);
225    void addSpecification(FunctionSpecification* spec) { mSpecifications.push_back(spec); }
226};
227
228/* Base class for TypeSpecification, ConstantSpecification, and FunctionSpecification.
229 * A specification can be specific to a range of RenderScript version or 32bits vs 64 bits.
230 * This base class contains code to parse and store this version information.
231 */
232class Specification {
233protected:
234    VersionInfo mVersionInfo;
235    void scanVersionInfo(Scanner* scanner);
236
237public:
238    VersionInfo getVersionInfo() const { return mVersionInfo; }
239};
240
241/* Defines one of the many variations of a constant.  There's a one to one correspondance between
242 * ConstantSpecification objects and entries in the spec file.
243 */
244class ConstantSpecification : public Specification {
245private:
246    Constant* mConstant;  // Not owned
247
248    std::string mValue;  // E.g. "3.1415"
249public:
250    ConstantSpecification(Constant* constant) : mConstant(constant) {}
251
252    Constant* getConstant() const { return mConstant; }
253    std::string getValue() const { return mValue; }
254
255    // Parse a constant specification and add it to specFile.
256    static void scanConstantSpecification(Scanner* scanner, SpecFile* specFile, int maxApiLevel);
257};
258
259enum TypeKind {
260    SIMPLE,
261    STRUCT,
262    ENUM,
263};
264
265/* Defines one of the many variations of a type.  There's a one to one correspondance between
266 * TypeSpecification objects and entries in the spec file.
267 */
268class TypeSpecification : public Specification {
269private:
270    Type* mType;  // Not owned
271
272    TypeKind mKind;  // The kind of type specification
273
274    // If mKind is SIMPLE:
275    std::string mSimpleType;  // The definition of the type
276
277    // If mKind is STRUCT:
278    std::string mStructName;                  // The name found after the struct keyword
279    std::vector<std::string> mFields;         // One entry per struct field
280    std::vector<std::string> mFieldComments;  // One entry per struct field
281    std::string mAttrib;                      // Some structures may have attributes
282
283    // If mKind is ENUM:
284    std::string mEnumName;                    // The name found after the enum keyword
285    std::vector<std::string> mValues;         // One entry per enum value
286    std::vector<std::string> mValueComments;  // One entry per enum value
287public:
288    TypeSpecification(Type* type) : mType(type) {}
289
290    Type* getType() const { return mType; }
291    TypeKind getKind() const { return mKind; }
292    std::string getSimpleType() const { return mSimpleType; }
293    std::string getStructName() const { return mStructName; }
294    const std::vector<std::string>& getFields() const { return mFields; }
295    const std::vector<std::string>& getFieldComments() const { return mFieldComments; }
296    std::string getAttrib() const { return mAttrib; }
297    std::string getEnumName() const { return mEnumName; }
298    const std::vector<std::string>& getValues() const { return mValues; }
299    const std::vector<std::string>& getValueComments() const { return mValueComments; }
300
301    // Parse a type specification and add it to specFile.
302    static void scanTypeSpecification(Scanner* scanner, SpecFile* specFile, int maxApiLevel);
303};
304
305// Maximum number of placeholders (like #1, #2) in function specifications.
306const int MAX_REPLACEABLES = 4;
307
308/* Defines one of the many variations of the function.  There's a one to one correspondance between
309 * FunctionSpecification objects and entries in the spec file.  Some of the strings that are parts
310 * of a FunctionSpecification can include placeholders, which are "#1", "#2", "#3", and "#4".  We'll
311 * replace these by values before generating the files.
312 */
313class FunctionSpecification : public Specification {
314private:
315    Function* mFunction;  // Not owned
316
317    /* How to test.  One of:
318     * "scalar": Generate test code that checks entries of each vector indepently.  E.g. for
319     *           sin(float3), the test code will call the CoreMathVerfier.computeSin 3 times.
320     * "limited": Like "scalar" but we don't generate extreme values.  This is not currently
321     *            enabled as we were generating to many errors.
322     * "custom": Like "scalar" but instead of calling CoreMathVerifier.computeXXX() to compute
323     *           the expected value, we call instead CoreMathVerifier.verifyXXX().  This method
324     *           returns a string that contains the error message, null if there's no error.
325     * "vector": Generate test code that calls the CoreMathVerifier only once for each vector.
326     *           This is useful for APIs like dot() or length().
327     * "noverify": Generate test code that calls the API but don't verify the returned value.
328     *             This can discover unresolved references.
329     * "": Don't test.  This is the default.
330     */
331    std::string mTest;
332    std::string mAttribute;       // Function attributes.
333    std::string mPrecisionLimit;  // Maximum precision required when checking output of this
334                                  // function.
335
336    // The vectors of values with which we'll replace #1, #2, ...
337    std::vector<std::vector<std::string> > mReplaceables;
338
339    /* The collection of permutations for this specification, i.e. this class instantianted
340     * for specific values of #1, #2, etc.  Owned.
341     */
342    std::vector<FunctionPermutation*> mPermutations;
343
344    // The following fields may contain placeholders that will be replaced using the mReplaceables.
345
346    /* As of this writing, convert_... is the only function with #1 in its name.
347     * The related Function object contains the name of the function without #n, e.g. convert.
348     * This is the name with the #, e.g. convert_#1_#2
349     */
350    std::string mUnexpandedName;
351    ParameterEntry* mReturn;                   // The return type. The name should be empty.  Owned.
352    std::vector<ParameterEntry*> mParameters;  // The parameters.  Owned.
353    std::vector<std::string> mInline;          // The inline code to be included in the header
354
355    /* Substitute the placeholders in the strings (e.g. #1, #2, ...) by the corresponding
356     * entries in mReplaceables.  indexOfReplaceable1 selects with value to use for #1,
357     * same for 2, 3, and 4.
358     */
359    std::string expandString(std::string s, int indexOfReplaceable[MAX_REPLACEABLES]) const;
360    void expandStringVector(const std::vector<std::string>& in,
361                            int replacementIndexes[MAX_REPLACEABLES],
362                            std::vector<std::string>* out) const;
363
364    // Fill the mPermutations field.
365    void createPermutations(Function* function, Scanner* scanner);
366
367public:
368    FunctionSpecification(Function* function) : mFunction(function), mReturn(nullptr) {}
369    ~FunctionSpecification();
370
371    Function* getFunction() { return mFunction; }
372    std::string getAttribute() const { return mAttribute; }
373    std::string getTest() const { return mTest; }
374    std::string getPrecisionLimit() const { return mPrecisionLimit; }
375
376    const std::vector<FunctionPermutation*>& getPermutations() const { return mPermutations; }
377
378    std::string getName(int replacementIndexes[MAX_REPLACEABLES]) const;
379    void getReturn(int replacementIndexes[MAX_REPLACEABLES], std::string* retType,
380                   int* lineNumber) const;
381    size_t getNumberOfParams() const { return mParameters.size(); }
382    void getParam(size_t index, int replacementIndexes[MAX_REPLACEABLES], std::string* type,
383                  std::string* name, std::string* testOption, int* lineNumber) const;
384    void getInlines(int replacementIndexes[MAX_REPLACEABLES],
385                    std::vector<std::string>* inlines) const;
386
387    // Parse the "test:" line.
388    void parseTest(Scanner* scanner);
389
390    // Return true if we need to generate tests for this function.
391    bool hasTests(int versionOfTestFiles) const;
392
393    // Parse a function specification and add it to specFile.
394    static void scanFunctionSpecification(Scanner* scanner, SpecFile* specFile, int maxApiLevel);
395};
396
397/* A concrete version of a function specification, where all placeholders have been replaced by
398 * actual values.
399 */
400class FunctionPermutation {
401private:
402    // These are the expanded version of those found on FunctionSpecification
403    std::string mName;
404    std::string mNameTrunk;  // The name without any expansion, e.g. convert
405    std::string mTest;       // How to test.  One of "scalar", "vector", "noverify", "limited", and
406                             // "none".
407    std::string mPrecisionLimit;  // Maximum precision required when checking output of this
408                                  // function.
409
410    // The parameters of the function.  This does not include the return type.  Owned.
411    std::vector<ParameterDefinition*> mParams;
412    // The return type.  nullptr if a void function.  Owned.
413    ParameterDefinition* mReturn;
414
415    // The number of input and output parameters.  mOutputCount counts the return type.
416    int mInputCount;
417    int mOutputCount;
418
419    // Whether one of the output parameters is a float.
420    bool mHasFloatAnswers;
421
422    // The inline code that implements this function.  Will be empty if not an inline.
423    std::vector<std::string> mInline;
424
425public:
426    FunctionPermutation(Function* function, FunctionSpecification* specification,
427                        int replacementIndexes[MAX_REPLACEABLES], Scanner* scanner);
428    ~FunctionPermutation();
429
430    std::string getName() const { return mName; }
431    std::string getNameTrunk() const { return mNameTrunk; }
432    std::string getTest() const { return mTest; }
433    std::string getPrecisionLimit() const { return mPrecisionLimit; }
434
435    const std::vector<std::string>& getInline() const { return mInline; }
436    const ParameterDefinition* getReturn() const { return mReturn; }
437    int getInputCount() const { return mInputCount; }
438    int getOutputCount() const { return mOutputCount; }
439    bool hasFloatAnswers() const { return mHasFloatAnswers; }
440
441    const std::vector<ParameterDefinition*> getParams() const { return mParams; }
442};
443
444// An entire spec file and the methods to process it.
445class SpecFile {
446private:
447    std::string mSpecFileName;
448    std::string mHeaderFileName;
449    std::string mDetailedDocumentationUrl;
450    std::string mBriefDescription;
451    std::vector<std::string> mFullDescription;
452    // Text to insert as-is in the generated header.
453    std::vector<std::string> mVerbatimInclude;
454
455    /* The constants, types, and functions specifications declared in this
456     *  file, in the order they are found in the file.  This matters for
457     * header generation, as some types and inline functions depend
458     * on each other.  Pointers not owned.
459     */
460    std::list<ConstantSpecification*> mConstantSpecificationsList;
461    std::list<TypeSpecification*> mTypeSpecificationsList;
462    std::list<FunctionSpecification*> mFunctionSpecificationsList;
463
464    /* The constants, types, and functions that are documented in this file.
465     * In very rare cases, specifications for an API are split across multiple
466     * files, e.g. currently for ClearObject().  The documentation for
467     * that function must be found in the first spec file encountered, so the
468     * order of the files on the command line matters.
469     */
470    std::map<std::string, Constant*> mDocumentedConstants;
471    std::map<std::string, Type*> mDocumentedTypes;
472    std::map<std::string, Function*> mDocumentedFunctions;
473
474public:
475    explicit SpecFile(const std::string& specFileName);
476
477    std::string getSpecFileName() const { return mSpecFileName; }
478    std::string getHeaderFileName() const { return mHeaderFileName; }
479    std::string getDetailedDocumentationUrl() const { return mDetailedDocumentationUrl; }
480    const std::string getBriefDescription() const { return mBriefDescription; }
481    const std::vector<std::string>& getFullDescription() const { return mFullDescription; }
482    const std::vector<std::string>& getVerbatimInclude() const { return mVerbatimInclude; }
483
484    const std::list<ConstantSpecification*>& getConstantSpecifications() const {
485        return mConstantSpecificationsList;
486    }
487    const std::list<TypeSpecification*>& getTypeSpecifications() const {
488        return mTypeSpecificationsList;
489    }
490    const std::list<FunctionSpecification*>& getFunctionSpecifications() const {
491        return mFunctionSpecificationsList;
492    }
493    const std::map<std::string, Constant*>& getDocumentedConstants() const {
494        return mDocumentedConstants;
495    }
496    const std::map<std::string, Type*>& getDocumentedTypes() const { return mDocumentedTypes; }
497    const std::map<std::string, Function*>& getDocumentedFunctions() const {
498        return mDocumentedFunctions;
499    }
500
501    bool hasSpecifications() const {
502        return !mDocumentedConstants.empty() || !mDocumentedTypes.empty() ||
503               !mDocumentedFunctions.empty();
504    }
505
506    bool readSpecFile(int maxApiLevel);
507
508    /* These are called by the parser to keep track of the specifications defined in this file.
509     * hasDocumentation is true if this specification containes the documentation.
510     */
511    void addConstantSpecification(ConstantSpecification* spec, bool hasDocumentation);
512    void addTypeSpecification(TypeSpecification* spec, bool hasDocumentation);
513    void addFunctionSpecification(FunctionSpecification* spec, bool hasDocumentation);
514};
515
516// The collection of all the spec files.
517class SystemSpecification {
518private:
519    std::vector<SpecFile*> mSpecFiles;
520
521    /* Entries in the table of contents.  We accumulate them in a map to sort them.
522     * Pointers are owned.
523     */
524    std::map<std::string, Constant*> mConstants;
525    std::map<std::string, Type*> mTypes;
526    std::map<std::string, Function*> mFunctions;
527
528public:
529    ~SystemSpecification();
530
531    /* These are called the parser to create unique instances per name.  Set *created to true
532     * if the named specification did not already exist.
533     */
534    Constant* findOrCreateConstant(const std::string& name, bool* created);
535    Type* findOrCreateType(const std::string& name, bool* created);
536    Function* findOrCreateFunction(const std::string& name, bool* created);
537
538    /* Parse the spec file and create the object hierarchy, adding a pointer to mSpecFiles.
539     * We won't include information passed the specified level.
540     */
541    bool readSpecFile(const std::string& fileName, int maxApiLevel);
542    // Generate all the files.
543    bool generateFiles(bool forVerification, int maxApiLevel) const;
544
545    const std::vector<SpecFile*>& getSpecFiles() const { return mSpecFiles; }
546    const std::map<std::string, Constant*>& getConstants() const { return mConstants; }
547    const std::map<std::string, Type*>& getTypes() const { return mTypes; }
548    const std::map<std::string, Function*>& getFunctions() const { return mFunctions; }
549
550    // Returns "<a href='...'> for the named specification, or empty if not found.
551    std::string getHtmlAnchor(const std::string& name) const;
552};
553
554// Singleton that represents the collection of all the specs we're processing.
555extern SystemSpecification systemSpecification;
556
557// Table of equivalences of numerical types.
558extern const NumericalType TYPES[];
559extern const int NUM_TYPES;
560
561#endif  // ANDROID_RS_API_GENERATOR_SPECIFICATION_H
562