Home | History | Annotate | Download | only in api
      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 #include <algorithm>
     18 #include <climits>
     19 #include <iostream>
     20 #include <iterator>
     21 #include <sstream>
     22 
     23 #include "Generator.h"
     24 #include "Specification.h"
     25 #include "Utilities.h"
     26 
     27 using namespace std;
     28 
     29 const unsigned int kMinimumApiLevelForTests = 11;
     30 const unsigned int kApiLevelWithFirst64Bit = 21;
     31 
     32 // Used to map the built-in types to their mangled representations
     33 struct BuiltInMangling {
     34     const char* token[3];     // The last two entries can be nullptr
     35     const char* equivalence;  // The mangled equivalent
     36 };
     37 
     38 BuiltInMangling builtInMangling[] = {
     39             {{"long", "long"}, "x"},
     40             {{"unsigned", "long", "long"}, "y"},
     41             {{"long"}, "l"},
     42             {{"unsigned", "long"}, "m"},
     43             {{"int"}, "i"},
     44             {{"unsigned", "int"}, "j"},
     45             {{"short"}, "s"},
     46             {{"unsigned", "short"}, "t"},
     47             {{"char"}, "c"},
     48             {{"unsigned", "char"}, "h"},
     49             {{"signed", "char"}, "a"},
     50             {{"void"}, "v"},
     51             {{"wchar_t"}, "w"},
     52             {{"bool"}, "b"},
     53             {{"__fp16"}, "Dh"},
     54             {{"float"}, "f"},
     55             {{"double"}, "d"},
     56 };
     57 
     58 /* For the given API level and bitness (e.g. 32 or 64 bit), try to find a
     59  * substitution for the provided type name, as would be done (mostly) by a
     60  * preprocessor.  Returns empty string if there's no substitution.
     61  */
     62 static string findSubstitute(const string& typeName, unsigned int apiLevel, int intSize) {
     63     const auto& types = systemSpecification.getTypes();
     64     const auto type = types.find(typeName);
     65     if (type != types.end()) {
     66         for (TypeSpecification* spec : type->second->getSpecifications()) {
     67             // Verify this specification applies
     68             const VersionInfo info = spec->getVersionInfo();
     69             if (!info.includesVersion(apiLevel) || (info.intSize != 0 && info.intSize != intSize)) {
     70                 continue;
     71             }
     72             switch (spec->getKind()) {
     73                 case SIMPLE: {
     74                     return spec->getSimpleType();
     75                 }
     76                 case RS_OBJECT: {
     77                     // Do nothing for RS object types.
     78                     break;
     79                 }
     80                 case STRUCT: {
     81                     return spec->getStructName();
     82                 }
     83                 case ENUM:
     84                     // Do nothing
     85                     break;
     86             }
     87         }
     88     }
     89     return "";
     90 }
     91 
     92 /* Expand the typedefs found in 'type' into their equivalents and tokenize
     93  * the resulting list.  'apiLevel' and 'intSize' specifies the API level and bitness
     94  * we are currently processing.
     95  */
     96 list<string> expandTypedefs(const string type, unsigned int apiLevel, int intSize, string& vectorSize) {
     97     // Split the string in tokens.
     98     istringstream stream(type);
     99     list<string> tokens{istream_iterator<string>{stream}, istream_iterator<string>{}};
    100     // Try to substitue each token.
    101     for (auto i = tokens.begin(); i != tokens.end();) {
    102         const string substitute = findSubstitute(*i, apiLevel, intSize);
    103         if (substitute.empty()) {
    104             // No substitution possible, just go to the next token.
    105             i++;
    106         } else {
    107             // Split the replacement string in tokens.
    108             istringstream stream(substitute);
    109 
    110             /* Get the new vector size. This is for the case of the type being for example
    111              * rs_quaternion* == float4*, where we need the vector size to be 4 for the
    112              * purposes of mangling, although the parameter itself is not determined to be
    113              * a vector. */
    114             string unused;
    115             string newVectorSize;
    116             getVectorSizeAndBaseType(*i, newVectorSize, unused);
    117 
    118             istringstream vectorSizeBuf(vectorSize);
    119             int vectorSizeVal;
    120             vectorSizeBuf >> vectorSizeVal;
    121 
    122             istringstream newVectorSizeBuf(newVectorSize);
    123             int newVectorSizeVal;
    124             newVectorSizeBuf >> newVectorSizeVal;
    125 
    126             if (newVectorSizeVal > vectorSizeVal)
    127                 vectorSize = newVectorSize;
    128 
    129             list<string> newTokens{istream_iterator<string>{stream}, istream_iterator<string>{}};
    130             // Replace the token with the substitution. Don't advance, as the new substitution
    131             // might itself be replaced.
    132             auto prev = i;
    133             --prev;
    134             tokens.insert(i, newTokens.begin(), newTokens.end());
    135             tokens.erase(i);
    136             advance(i, -newTokens.size());
    137         }
    138     }
    139     return tokens;
    140 }
    141 
    142 // Remove the first element of the list if it equals 'prefix'.  Return true in that case.
    143 static bool eatFront(list<string>* tokens, const char* prefix) {
    144     if (tokens->front() == prefix) {
    145         tokens->pop_front();
    146         return true;
    147     }
    148     return false;
    149 }
    150 
    151 /* Search the table of translations for the built-ins for the mangling that
    152  * corresponds to this list of tokens.  If a match is found, consume these tokens
    153  * and return a pointer to the string.  If not, return nullptr.
    154  */
    155 static const char* findManglingOfBuiltInType(list<string>* tokens) {
    156     for (const BuiltInMangling& a : builtInMangling) {
    157         auto t = tokens->begin();
    158         auto end = tokens->end();
    159         bool match = true;
    160         // We match up to three tokens.
    161         for (int i = 0; i < 3; i++) {
    162             if (!a.token[i]) {
    163                 // No more tokens
    164                 break;
    165             }
    166             if (t == end || *t++ != a.token[i]) {
    167                 match = false;
    168             }
    169         }
    170         if (match) {
    171             tokens->erase(tokens->begin(), t);
    172             return a.equivalence;
    173         }
    174     }
    175     return nullptr;
    176 }
    177 
    178 // Mangle a long name by prefixing it with its length, e.g. "13rs_allocation".
    179 static inline string mangleLongName(const string& name) {
    180     return to_string(name.size()) + name;
    181 }
    182 
    183 /* Mangle the type name that's represented by the vector size and list of tokens.
    184  * The mangling will be returned in full form in 'mangling'.  'compressedMangling'
    185  * will have the compressed equivalent.  This is built using the 'previousManglings'
    186  * list.  false is returned if an error is encountered.
    187  *
    188  * This function is recursive because compression is possible at each level of the definition.
    189  * See http://mentorembedded.github.io/cxx-abi/abi.html#mangle.type for a description
    190  * of the Itanium mangling used by llvm.
    191  *
    192  * This function mangles correctly the types currently used by RenderScript.  It does
    193  * not currently mangle more complicated types like function pointers, namespaces,
    194  * or other C++ types.  In particular, we don't deal correctly with parenthesis.
    195  */
    196 static bool mangleType(string vectorSize, list<string>* tokens, vector<string>* previousManglings,
    197                        string* mangling, string* compressedMangling) {
    198     string delta;                 // The part of the mangling we're generating for this recursion.
    199     bool isTerminal = false;      // True if this iteration parses a terminal node in the production.
    200     bool canBeCompressed = true;  // Will be false for manglings of builtins.
    201 
    202     if (tokens->back() == "*") {
    203         delta = "P";
    204         tokens->pop_back();
    205     } else if (eatFront(tokens, "const")) {
    206         delta = "K";
    207     } else if (eatFront(tokens, "volatile")) {
    208         delta = "V";
    209     } else if (vectorSize != "1" && vectorSize != "") {
    210         // For vector, prefix with the abbreviation for a vector, including the size.
    211         delta = "Dv" + vectorSize + "_";
    212         vectorSize.clear();  // Reset to mark the size as consumed.
    213     } else if (eatFront(tokens, "struct")) {
    214         // For a structure, we just use the structure name
    215         if (tokens->size() == 0) {
    216             cerr << "Expected a name after struct\n";
    217             return false;
    218         }
    219         delta = mangleLongName(tokens->front());
    220         isTerminal = true;
    221         tokens->pop_front();
    222     } else if (eatFront(tokens, "...")) {
    223         delta = "z";
    224         isTerminal = true;
    225     } else {
    226         const char* c = findManglingOfBuiltInType(tokens);
    227         if (c) {
    228             // It's a basic type.  We don't use those directly for compression.
    229             delta = c;
    230             isTerminal = true;
    231             canBeCompressed = false;
    232         } else if (tokens->size() > 0) {
    233             // It's a complex type name.
    234             delta = mangleLongName(tokens->front());
    235             isTerminal = true;
    236             tokens->pop_front();
    237         }
    238     }
    239 
    240     if (isTerminal) {
    241         // If we're the terminal node, there should be nothing left to mangle.
    242         if (tokens->size() > 0) {
    243             cerr << "Expected nothing else but found";
    244             for (const auto& t : *tokens) {
    245                 cerr << " " << t;
    246             }
    247             cerr << "\n";
    248             return false;
    249         }
    250         *mangling = delta;
    251         *compressedMangling = delta;
    252     } else {
    253         // We're not terminal.  Recurse and prefix what we've translated this pass.
    254         if (tokens->size() == 0) {
    255             cerr << "Expected a more complete type\n";
    256             return false;
    257         }
    258         string rest, compressedRest;
    259         if (!mangleType(vectorSize, tokens, previousManglings, &rest, &compressedRest)) {
    260             return false;
    261         }
    262         *mangling = delta + rest;
    263         *compressedMangling = delta + compressedRest;
    264     }
    265 
    266     /* If it's a built-in type, we don't look at previously emitted ones and we
    267      * don't keep track of it.
    268      */
    269     if (!canBeCompressed) {
    270         return true;
    271     }
    272 
    273     // See if we've encountered this mangling before.
    274     for (size_t i = 0; i < previousManglings->size(); ++i) {
    275         if ((*previousManglings)[i] == *mangling) {
    276             // We have a match, construct an index reference to that previously emitted mangling.
    277             ostringstream stream2;
    278             stream2 << 'S';
    279             if (i > 0) {
    280                 stream2 << (char)('0' + i - 1);
    281             }
    282             stream2 << '_';
    283             *compressedMangling = stream2.str();
    284             return true;
    285         }
    286     }
    287 
    288     // We have not encountered this before.  Add it to the list.
    289     previousManglings->push_back(*mangling);
    290     return true;
    291 }
    292 
    293 // Write to the stream the mangled representation of each parameter.
    294 static bool writeParameters(ostringstream* stream, const std::vector<ParameterDefinition*>& params,
    295                             unsigned int apiLevel, int intSize) {
    296     if (params.empty()) {
    297         *stream << "v";
    298         return true;
    299     }
    300     /* We keep track of the previously generated parameter types, as type mangling
    301      * is compressed by reusing previous manglings.
    302      */
    303     vector<string> previousManglings;
    304     for (ParameterDefinition* p : params) {
    305         // Expand the typedefs and create a tokenized list.
    306         string vectorSize = p->mVectorSize;
    307         list<string> tokens = expandTypedefs(p->rsType, apiLevel, intSize, vectorSize);
    308         if (p->isOutParameter) {
    309             tokens.push_back("*");
    310         }
    311         string mangling, compressedMangling;
    312 
    313         if (!mangleType(vectorSize, &tokens, &previousManglings, &mangling,
    314                         &compressedMangling)) {
    315             return false;
    316         }
    317         *stream << compressedMangling;
    318     }
    319     return true;
    320 }
    321 
    322 /* Add the mangling for this permutation of the function.  apiLevel and intSize is used
    323  * to select the correct type when expanding complex type.
    324  */
    325 static bool addFunctionManglingToSet(const Function& function,
    326                                      const FunctionPermutation& permutation, bool overloadable,
    327                                      unsigned int apiLevel, int intSize, set<string>* allManglings) {
    328     const string& functionName = permutation.getName();
    329     string mangling;
    330     if (overloadable) {
    331         ostringstream stream;
    332         stream << "_Z" << mangleLongName(functionName);
    333         if (!writeParameters(&stream, permutation.getParams(), apiLevel, intSize)) {
    334             cerr << "Error mangling " << functionName << ".  See above message.\n";
    335             return false;
    336         }
    337         mangling = stream.str();
    338     } else {
    339         mangling = functionName;
    340     }
    341     allManglings->insert(mangling);
    342     return true;
    343 }
    344 
    345 /* Add to the set the mangling of each function prototype that can be generated from this
    346  * specification, i.e. for all the versions covered and for 32/64 bits.  We call this
    347  * for each API level because the implementation of a type may have changed in the range
    348  * of API levels covered.
    349  */
    350 static bool addManglingsForSpecification(const Function& function,
    351                                          const FunctionSpecification& spec, unsigned int lastApiLevel,
    352                                          set<string>* allManglings) {
    353     // If the function is inlined, we won't generate an unresolved external for that.
    354     if (spec.hasInline()) {
    355         return true;
    356     }
    357     const VersionInfo info = spec.getVersionInfo();
    358     unsigned int minApiLevel, maxApiLevel;
    359     minApiLevel = info.minVersion ? info.minVersion : kMinimumApiLevelForTests;
    360     maxApiLevel = info.maxVersion ? info.maxVersion : lastApiLevel;
    361     const bool overloadable = spec.isOverloadable();
    362 
    363     /* We track success rather than aborting early in case of failure so that we
    364      * generate all the error messages.
    365      */
    366     bool success = true;
    367     // Use 64-bit integer here for the loop count to avoid overflow
    368     // (minApiLevel == maxApiLevel == UINT_MAX for unreleased API)
    369     for (int64_t apiLevel = minApiLevel; apiLevel <= maxApiLevel; ++apiLevel) {
    370         for (auto permutation : spec.getPermutations()) {
    371             if (info.intSize == 0 || info.intSize == 32) {
    372                 if (!addFunctionManglingToSet(function, *permutation, overloadable, apiLevel, 32,
    373                                               allManglings)) {
    374                     success = false;
    375                 }
    376             }
    377             if (apiLevel >= kApiLevelWithFirst64Bit && (info.intSize == 0 || info.intSize == 64)) {
    378                 if (!addFunctionManglingToSet(function, *permutation, overloadable, apiLevel, 64,
    379                                               allManglings)) {
    380                     success = false;
    381                 }
    382             }
    383         }
    384     }
    385     return success;
    386 }
    387 
    388 /* Generate the white list file of the mangled function prototypes.  This generated list is used
    389  * to validate unresolved external references.  'lastApiLevel' is the largest api level found in
    390  * all spec files.
    391  */
    392 static bool generateWhiteListFile(unsigned int lastApiLevel) {
    393     bool success = true;
    394     // We generate all the manglings in a set to remove duplicates and to order them.
    395     set<string> allManglings;
    396     for (auto f : systemSpecification.getFunctions()) {
    397         const Function* function = f.second;
    398         for (auto spec : function->getSpecifications()) {
    399             // Compiler intrinsics are not runtime APIs. Do not include them in the whitelist.
    400             if (spec->isIntrinsic()) {
    401                 continue;
    402             }
    403             if (!addManglingsForSpecification(*function, *spec, lastApiLevel, &allManglings)) {
    404                 success = false;  // We continue so we can generate all errors.
    405             }
    406         }
    407     }
    408 
    409     if (success) {
    410         GeneratedFile file;
    411         if (!file.start(".", "RSStubsWhiteList.cpp")) {
    412             return false;
    413         }
    414 
    415         file.writeNotices();
    416         file << "#include \"RSStubsWhiteList.h\"\n\n";
    417         file << "std::vector<std::string> stubList = {\n";
    418         for (const auto& e : allManglings) {
    419             file << "\"" << e << "\",\n";
    420         }
    421         file << "};\n";
    422     }
    423     return success;
    424 }
    425 
    426 // Add a uniquely named variable definition to the file and return its name.
    427 static const string addVariable(GeneratedFile* file, unsigned int* variableNumber) {
    428     const string name = "buf" + to_string((*variableNumber)++);
    429     /* Some data structures like rs_tm can't be exported.  We'll just use a dumb buffer
    430      * and cast its address later on.
    431      */
    432     *file << "char " << name << "[200];\n";
    433     return name;
    434 }
    435 
    436 /* Write to the file the globals needed to make the call for this permutation.  The actual
    437  * call is stored in 'calls', as we'll need to generate all the global variable declarations
    438  * before the function definition.
    439  */
    440 static void generateTestCall(GeneratedFile* file, ostringstream* calls,
    441                              unsigned int* variableNumber, const Function& function,
    442                              const FunctionPermutation& permutation) {
    443     *calls << "    ";
    444 
    445     // Handle the return type.
    446     const auto ret = permutation.getReturn();
    447     if (ret && ret->rsType != "void" && ret->rsType != "const void") {
    448         *calls << "*(" << ret->rsType << "*)" << addVariable(file, variableNumber) << " = ";
    449     }
    450 
    451     *calls << permutation.getName() << "(";
    452 
    453     // Generate the arguments.
    454     const char* separator = "";
    455     for (auto p : permutation.getParams()) {
    456         *calls << separator;
    457         if (p->rsType == "rs_kernel_context") {
    458             // Special case for the kernel context, as it has a special existence.
    459             *calls << "context";
    460         } else if (p->rsType == "...") {
    461             // Special case for varargs. No need for casting.
    462             *calls << addVariable(file, variableNumber);
    463         } else if (p->isOutParameter) {
    464             *calls << "(" << p->rsType << "*) " << addVariable(file, variableNumber);
    465         } else {
    466             *calls << "*(" << p->rsType << "*)" << addVariable(file, variableNumber);
    467         }
    468         separator = ", ";
    469     }
    470     *calls << ");\n";
    471 }
    472 
    473 /* Generate a test file that will be used in the frameworks/compile/slang/tests unit tests.
    474  * This file tests that all RenderScript APIs can be called for the specified API level.
    475  * To avoid the compiler agressively pruning out our calls, we use globals as inputs and outputs.
    476  *
    477  * Since some structures can't be defined at the global level, we use casts of simple byte
    478  * buffers to get around that restriction.
    479  *
    480  * This file can be used to verify the white list that's also generated in this file.  To do so,
    481  * run "llvm-nm -undefined-only -just-symbol-name" on the resulting bit code.
    482  */
    483 static bool generateApiTesterFile(const string& slangTestDirectory, unsigned int apiLevel) {
    484     GeneratedFile file;
    485     if (!file.start(slangTestDirectory, "all" + to_string(apiLevel) + ".rs")) {
    486         return false;
    487     }
    488 
    489     /* This unusual comment is used by slang/tests/test.py to know which parameter to pass
    490      * to llvm-rs-cc when compiling the test.
    491      */
    492     file << "// -target-api " << apiLevel << " -Wno-deprecated-declarations\n";
    493 
    494     file.writeNotices();
    495     file << "#pragma version(1)\n";
    496     file << "#pragma rs java_package_name(com.example.renderscript.testallapi)\n\n";
    497     if (apiLevel < 23) {  // All rs_graphics APIs were deprecated in api level 23.
    498         file << "#include \"rs_graphics.rsh\"\n\n";
    499     }
    500 
    501     /* The code below emits globals and calls to functions in parallel.  We store
    502      * the calls in a stream so that we can emit them in the file in the proper order.
    503      */
    504     ostringstream calls;
    505     unsigned int variableNumber = 0;  // Used to generate unique names.
    506     for (auto f : systemSpecification.getFunctions()) {
    507         const Function* function = f.second;
    508         for (auto spec : function->getSpecifications()) {
    509             // Do not include internal APIs in the API tests.
    510             if (spec->isInternal()) {
    511                 continue;
    512             }
    513             VersionInfo info = spec->getVersionInfo();
    514             if (!info.includesVersion(apiLevel)) {
    515                 continue;
    516             }
    517             if (info.intSize == 32) {
    518                 calls << "#ifndef __LP64__\n";
    519             } else if (info.intSize == 64) {
    520                 calls << "#ifdef __LP64__\n";
    521             }
    522             for (auto permutation : spec->getPermutations()) {
    523                 // http://b/27358969 Do not test rsForEach in the all-api test.
    524                 if (apiLevel >= 24 && permutation->getName().compare(0, 9, "rsForEach") == 0)
    525                   continue;
    526                 generateTestCall(&file, &calls, &variableNumber, *function, *permutation);
    527             }
    528             if (info.intSize != 0) {
    529                 calls << "#endif\n";
    530             }
    531         }
    532     }
    533     file << "\n";
    534 
    535     // Modify the style of kernel as required by the API level.
    536     if (apiLevel >= 23) {
    537         file << "void RS_KERNEL test(int in, rs_kernel_context context) {\n";
    538     } else if (apiLevel >= 17) {
    539         file << "void RS_KERNEL test(int in) {\n";
    540     } else {
    541         file << "void root(const int* in) {\n";
    542     }
    543     file << calls.str();
    544     file << "}\n";
    545 
    546     return true;
    547 }
    548 
    549 bool generateStubsWhiteList(const string& slangTestDirectory, unsigned int maxApiLevel) {
    550     unsigned int lastApiLevel = min(systemSpecification.getMaximumApiLevel(), maxApiLevel);
    551     if (!generateWhiteListFile(lastApiLevel)) {
    552         return false;
    553     }
    554     // Generate a test file for each apiLevel.
    555     for (unsigned int i = kMinimumApiLevelForTests; i <= lastApiLevel; ++i) {
    556         if (!generateApiTesterFile(slangTestDirectory, i)) {
    557             return false;
    558         }
    559     }
    560     return true;
    561 }
    562