1//===-- ClangBuiltinsEmitter.cpp - Generate Clang builtins tables ---------===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8//
9// This tablegen backend emits Clang's builtins tables.
10//
11//===----------------------------------------------------------------------===//
12
13#include "TableGenBackends.h"
14#include "llvm/ADT/DenseSet.h"
15#include "llvm/ADT/MapVector.h"
16#include "llvm/ADT/STLExtras.h"
17#include "llvm/ADT/StringExtras.h"
18#include "llvm/ADT/StringSwitch.h"
19#include "llvm/Support/MathExtras.h"
20#include "llvm/TableGen/Error.h"
21#include "llvm/TableGen/Record.h"
22#include "llvm/TableGen/StringToOffsetTable.h"
23#include "llvm/TableGen/TableGenBackend.h"
24#include <sstream>
25
26using namespace llvm;
27
28namespace {
29enum class BuiltinType {
30 Builtin,
31 AtomicBuiltin,
32 LibBuiltin,
33 LangBuiltin,
34 TargetBuiltin,
35 TargetLibBuiltin,
36};
37
38class HeaderNameParser {
39public:
40 HeaderNameParser(const Record *Builtin) {
41 for (char c : Builtin->getValueAsString(FieldName: "Header")) {
42 if (std::islower(c))
43 HeaderName += static_cast<char>(std::toupper(c: c));
44 else if (c == '.' || c == '_' || c == '/' || c == '-')
45 HeaderName += '_';
46 else
47 PrintFatalError(ErrorLoc: Builtin->getLoc(), Msg: "Unexpected header name");
48 }
49 }
50
51 void Print(raw_ostream &OS) const { OS << HeaderName; }
52
53private:
54 std::string HeaderName;
55};
56
57struct Builtin {
58 BuiltinType BT;
59 std::string Name;
60 std::string Type;
61 std::string Attributes;
62
63 const Record *BuiltinRecord;
64
65 void EmitEnumerator(llvm::raw_ostream &OS) const {
66 OS << " BI";
67 // If there is a required name prefix, include its spelling in the
68 // enumerator.
69 if (auto *PrefixRecord =
70 BuiltinRecord->getValueAsOptionalDef(FieldName: "RequiredNamePrefix"))
71 OS << PrefixRecord->getValueAsString(FieldName: "Spelling");
72 OS << Name << ",\n";
73 }
74
75 void EmitInfo(llvm::raw_ostream &OS, const StringToOffsetTable &Table) const {
76 OS << " Builtin::Info{Builtin::Info::StrOffsets{"
77 << Table.GetStringOffset(Str: Name) << " /* " << Name << " */, "
78 << Table.GetStringOffset(Str: Type) << " /* " << Type << " */, "
79 << Table.GetStringOffset(Str: Attributes) << " /* " << Attributes << " */, ";
80 if (BT == BuiltinType::TargetBuiltin) {
81 const auto &Features = BuiltinRecord->getValueAsString(FieldName: "Features");
82 OS << Table.GetStringOffset(Str: Features) << " /* " << Features << " */";
83 } else {
84 OS << "0";
85 }
86 OS << "}, ";
87 if (BT == BuiltinType::LibBuiltin || BT == BuiltinType::TargetLibBuiltin) {
88 OS << "HeaderDesc::";
89 HeaderNameParser{BuiltinRecord}.Print(OS);
90 } else {
91 OS << "HeaderDesc::NO_HEADER";
92 }
93 OS << ", ";
94 if (BT == BuiltinType::LibBuiltin || BT == BuiltinType::LangBuiltin ||
95 BT == BuiltinType::TargetLibBuiltin) {
96 OS << BuiltinRecord->getValueAsString(FieldName: "Languages");
97 } else {
98 OS << "ALL_LANGUAGES";
99 }
100 OS << "},\n";
101 }
102
103 void EmitXMacro(llvm::raw_ostream &OS) const {
104 if (BuiltinRecord->getValueAsBit(FieldName: "RequiresUndef"))
105 OS << "#undef " << Name << '\n';
106 switch (BT) {
107 case BuiltinType::LibBuiltin:
108 OS << "LIBBUILTIN";
109 break;
110 case BuiltinType::LangBuiltin:
111 OS << "LANGBUILTIN";
112 break;
113 case BuiltinType::Builtin:
114 OS << "BUILTIN";
115 break;
116 case BuiltinType::AtomicBuiltin:
117 OS << "ATOMIC_BUILTIN";
118 break;
119 case BuiltinType::TargetBuiltin:
120 OS << "TARGET_BUILTIN";
121 break;
122 case BuiltinType::TargetLibBuiltin:
123 OS << "TARGET_HEADER_BUILTIN";
124 break;
125 }
126
127 OS << "(" << Name << ", \"" << Type << "\", \"" << Attributes << "\"";
128
129 switch (BT) {
130 case BuiltinType::LibBuiltin: {
131 OS << ", ";
132 HeaderNameParser{BuiltinRecord}.Print(OS);
133 [[fallthrough]];
134 }
135 case BuiltinType::LangBuiltin: {
136 OS << ", " << BuiltinRecord->getValueAsString(FieldName: "Languages");
137 break;
138 }
139 case BuiltinType::TargetLibBuiltin: {
140 OS << ", ";
141 HeaderNameParser{BuiltinRecord}.Print(OS);
142 OS << ", " << BuiltinRecord->getValueAsString(FieldName: "Languages");
143 [[fallthrough]];
144 }
145 case BuiltinType::TargetBuiltin: {
146 OS << ", \"" << BuiltinRecord->getValueAsString(FieldName: "Features") << "\"";
147 break;
148 }
149 case BuiltinType::AtomicBuiltin:
150 case BuiltinType::Builtin:
151 break;
152 }
153 OS << ")\n";
154 }
155};
156
157bool isIdentifierChar(char C) { return isAlnum(C) || C == '_'; }
158
159bool endsWithWord(StringRef S, StringRef Word) {
160 return S.ends_with(Suffix: Word) &&
161 (S.size() == Word.size() ||
162 !isIdentifierChar(C: S[S.size() - Word.size() - 1]));
163}
164
165bool consumeFrontWord(StringRef &S, StringRef Word) {
166 if (!S.starts_with(Prefix: Word))
167 return false;
168 if (S.size() > Word.size() && isIdentifierChar(C: S[Word.size()]))
169 return false;
170 S = S.drop_front(N: Word.size());
171 return true;
172}
173
174bool consumeBackWord(StringRef &S, StringRef Word) {
175 if (!endsWithWord(S, Word))
176 return false;
177 S = S.drop_back(N: Word.size());
178 return true;
179}
180
181/// Split a parameter list string into individual parameter type strings,
182/// respecting nested angle brackets (e.g. address_space<4>, _ExtVector<4,
183/// float>).
184SmallVector<StringRef> splitParams(StringRef Params) {
185 SmallVector<StringRef> Result;
186 if (Params.empty())
187 return Result;
188
189 int Depth = 0;
190 size_t Start = 0;
191 for (size_t I = 0, E = Params.size(); I < E; ++I) {
192 if (Params[I] == '<') {
193 ++Depth;
194 } else if (Params[I] == '>') {
195 --Depth;
196 } else if (Params[I] == ',' && Depth == 0) {
197 Result.push_back(Elt: Params.substr(Start, N: I - Start).trim());
198 Start = I + 1;
199 }
200 }
201 // Add the last parameter.
202 StringRef Last = Params.substr(Start).trim();
203 if (!Last.empty())
204 Result.push_back(Elt: Last);
205 return Result;
206}
207
208class PrototypeParser {
209public:
210 PrototypeParser(StringRef Substitution, const Record *Builtin)
211 : Loc(Builtin->getFieldLoc(FieldName: "Prototype")), Substitution(Substitution),
212 EnableOpenCLLong(Builtin->getValueAsBit(FieldName: "EnableOpenCLLong")) {
213 ParsePrototype(Prototype: Builtin->getValueAsString(FieldName: "Prototype"));
214 }
215
216 std::string takeTypeString() && { return std::move(Type); }
217
218private:
219 void ParsePrototype(StringRef Prototype) {
220 Prototype = Prototype.trim();
221
222 // Some builtins don't have an expressible prototype, simply emit an empty
223 // string for them.
224 if (Prototype.empty()) {
225 Type = "";
226 return;
227 }
228
229 ParseTypes(Prototype);
230 }
231
232 void ParseTypes(StringRef &Prototype) {
233 auto ReturnType = Prototype.take_until(F: [](char c) { return c == '('; });
234 ParseType(T: ReturnType);
235 Prototype = Prototype.drop_front(N: ReturnType.size() + 1);
236 if (!Prototype.ends_with(Suffix: ")"))
237 PrintFatalError(ErrorLoc: Loc, Msg: "Expected closing brace at end of prototype");
238 Prototype = Prototype.drop_back();
239
240 // Look through the input parameters.
241 for (StringRef Param : splitParams(Params: Prototype)) {
242 if (!Param.empty())
243 ParseType(T: Param);
244 }
245 }
246
247 void ParseType(StringRef T) {
248 T = T.trim();
249
250 auto ConsumeAddrSpace = [&]() -> std::optional<unsigned> {
251 T = T.trim();
252 if (!T.ends_with(Suffix: ">"))
253 return std::nullopt;
254
255 auto Open = T.find_last_of(C: '<');
256 if (Open == StringRef::npos)
257 PrintFatalError(ErrorLoc: Loc, Msg: "Mismatched angle-brackets in type");
258
259 StringRef BeforeOpen = T.slice(Start: 0, End: Open).rtrim();
260 if (!consumeBackWord(S&: BeforeOpen, Word: "address_space")) {
261 if (endsWithWord(S: BeforeOpen, Word: "_ExtVector") ||
262 endsWithWord(S: BeforeOpen, Word: "_Vector"))
263 return std::nullopt;
264 PrintFatalError(ErrorLoc: Loc,
265 Msg: "Only `address_space<N>` supported as a parameterized "
266 "pointer or reference type qualifier");
267 }
268
269 StringRef ArgStr = T.slice(Start: Open + 1, End: T.size() - 1);
270 T = BeforeOpen;
271
272 unsigned Number = 0;
273 if (ArgStr.getAsInteger(Radix: 10, Result&: Number))
274 PrintFatalError(
275 ErrorLoc: Loc, Msg: "Expected an integer argument to the address_space qualifier");
276 return Number;
277 };
278
279 if (T.consume_back(Suffix: "*")) {
280 // Pointers may have an address space qualifier immediately before them.
281 std::optional<unsigned> AS = ConsumeAddrSpace();
282 // Pointers can apply to already parsed types, like vectors.
283 if (!T.empty())
284 ParseType(T);
285 Type += "*";
286 if (AS)
287 Type += std::to_string(val: *AS);
288 } else if (consumeBackWord(S&: T, Word: "const")) {
289 if (!T.empty())
290 ParseType(T);
291 Type += "C";
292 } else if (consumeBackWord(S&: T, Word: "volatile")) {
293 if (!T.empty())
294 ParseType(T);
295 Type += "D";
296 } else if (consumeBackWord(S&: T, Word: "restrict")) {
297 if (!T.empty())
298 ParseType(T);
299 Type += "R";
300 } else if (T.consume_back(Suffix: "&")) {
301 // References may have an address space qualifier immediately before them.
302 std::optional<unsigned> AS = ConsumeAddrSpace();
303 ParseType(T);
304 Type += "&";
305 if (AS)
306 Type += std::to_string(val: *AS);
307 } else if (T.consume_back(Suffix: ")")) {
308 ParseType(T);
309 Type += "&";
310 } else if (consumeFrontWord(S&: T, Word: "const")) {
311 if (!T.empty())
312 ParseType(T);
313 Type += "C";
314 } else if (consumeFrontWord(S&: T, Word: "volatile")) {
315 if (!T.empty())
316 ParseType(T);
317 Type += "D";
318 } else if (EnableOpenCLLong && T.consume_front(Prefix: "long long")) {
319 Type += "O";
320 ParseType(T);
321 } else if (T.consume_front(Prefix: "long")) {
322 Type += "L";
323 ParseType(T);
324 } else if (T.consume_front(Prefix: "signed")) {
325 Type += "S";
326 ParseType(T);
327 } else if (T.consume_front(Prefix: "unsigned")) {
328 Type += "U";
329 ParseType(T);
330 } else if (T.consume_front(Prefix: "_Complex")) {
331 Type += "X";
332 ParseType(T);
333 } else if (T.consume_front(Prefix: "_Constant")) {
334 Type += "I";
335 ParseType(T);
336 } else if (T.consume_front(Prefix: "T")) {
337 if (Substitution.empty())
338 PrintFatalError(ErrorLoc: Loc, Msg: "Not a template");
339 ParseType(T: Substitution);
340 } else if (auto IsExt = T.consume_front(Prefix: "_ExtVector");
341 IsExt || T.consume_front(Prefix: "_Vector")) {
342 // Clang extended vector types are mangled as follows:
343 //
344 // '_ExtVector<' <lanes> ',' <scalar type> '>'
345
346 // Before parsing T(=<scalar type>), make sure the syntax of
347 // `_ExtVector<N, T>` is correct...
348 if (!T.consume_front(Prefix: "<"))
349 PrintFatalError(ErrorLoc: Loc, Msg: "Expected '<' after '_ExtVector'");
350 unsigned long long Lanes;
351 if (consumeUnsignedInteger(Str&: T, Radix: 10, Result&: Lanes))
352 PrintFatalError(ErrorLoc: Loc, Msg: "Expected number of lanes after '_ExtVector<'");
353 Type += (IsExt ? "E" : "V") + std::to_string(val: Lanes);
354 if (!T.consume_front(Prefix: ","))
355 PrintFatalError(ErrorLoc: Loc,
356 Msg: "Expected ',' after number of lanes in '_ExtVector<'");
357 if (!T.consume_back(Suffix: ">"))
358 PrintFatalError(
359 ErrorLoc: Loc, Msg: "Expected '>' after scalar type in '_ExtVector<N, type>'");
360
361 // ...all good, we can check if we have a valid `<scalar type>`.
362 ParseType(T);
363 } else {
364 auto ReturnTypeVal = StringSwitch<std::string>(T)
365 .Case(S: "__builtin_va_list_ref", Value: "A")
366 .Case(S: "__builtin_va_list", Value: "a")
367 .Case(S: "__float128", Value: "LLd")
368 .Case(S: "__fp16", Value: "h")
369 .Case(S: "__hlsl_resource_t", Value: "Qr")
370 .Case(S: "__amdgpu_buffer_rsrc_t", Value: "Qb")
371 .Case(S: "__amdgpu_feature_predicate_t", Value: "Qc")
372 .Case(S: "__amdgpu_texture_t", Value: "Qt")
373 .Case(S: "__int128_t", Value: "LLLi")
374 .Case(S: "__uint128_t", Value: "ULLLi")
375 .Case(S: "_Float16", Value: "x")
376 .Case(S: "__bf16", Value: "y")
377 .Case(S: "bool", Value: "b")
378 .Case(S: "char", Value: "c")
379 .Case(S: "constant_CFString", Value: "F")
380 .Case(S: "double", Value: "d")
381 .Case(S: "FILE", Value: "P")
382 .Case(S: "float", Value: "f")
383 .Case(S: "id", Value: "G")
384 .Case(S: "int", Value: "i")
385 .Case(S: "int8_t", Value: "Bi")
386 .Case(S: "int16_t", Value: "Ti")
387 .Case(S: "int32_t", Value: "Zi")
388 .Case(S: "int64_t", Value: "Wi")
389 .Case(S: "jmp_buf", Value: "J")
390 .Case(S: "msint32_t", Value: "Ni")
391 .Case(S: "msuint32_t", Value: "UNi")
392 .Case(S: "objc_super", Value: "M")
393 .Case(S: "pid_t", Value: "p")
394 .Case(S: "ptrdiff_t", Value: "Y")
395 .Case(S: "SEL", Value: "H")
396 .Case(S: "short", Value: "s")
397 .Case(S: "sigjmp_buf", Value: "SJ")
398 .Case(S: "size_t", Value: "z")
399 .Case(S: "std::meta::info", Value: "r")
400 .Case(S: "ucontext_t", Value: "K")
401 .Case(S: "uint8_t", Value: "UBi")
402 .Case(S: "uint16_t", Value: "UTi")
403 .Case(S: "uint32_t", Value: "UZi")
404 .Case(S: "uint64_t", Value: "UWi")
405 .Case(S: "uint_least8_t", Value: "lUBi")
406 .Case(S: "uint_least16_t", Value: "lUTi")
407 .Case(S: "uint_least32_t", Value: "lUZi")
408 .Case(S: "uint_least64_t", Value: "lUWi")
409 .Case(S: "int_least8_t", Value: "lBi")
410 .Case(S: "int_least16_t", Value: "lTi")
411 .Case(S: "int_least32_t", Value: "lZi")
412 .Case(S: "int_least64_t", Value: "lWi")
413 .Case(S: "void", Value: "v")
414 .Case(S: "wchar_t", Value: "w")
415 .Case(S: "...", Value: ".")
416 .Default(Value: "error");
417 if (ReturnTypeVal == "error")
418 PrintFatalError(ErrorLoc: Loc, Msg: "Unknown Type: " + T);
419 Type += ReturnTypeVal;
420 }
421 }
422
423 SMLoc Loc;
424 StringRef Substitution;
425 bool EnableOpenCLLong;
426 std::string Type;
427};
428
429std::string renderAttributes(const Record *Builtin, BuiltinType BT) {
430 std::string Attributes;
431 raw_string_ostream OS(Attributes);
432 if (Builtin->isSubClassOf(Name: "LibBuiltin")) {
433 if (BT == BuiltinType::LibBuiltin) {
434 OS << 'f';
435 } else {
436 OS << 'F';
437 if (Builtin->getValueAsBit(FieldName: "OnlyBuiltinPrefixedAliasIsConstexpr"))
438 OS << 'E';
439 }
440 }
441
442 if (auto NS = Builtin->getValueAsOptionalString(FieldName: "Namespace")) {
443 if (NS != "std")
444 PrintFatalError(ErrorLoc: Builtin->getFieldLoc(FieldName: "Namespace"), Msg: "Unknown namespace: ");
445 OS << "z";
446 }
447
448 SmallVector<const Record *> ArgRanges;
449 for (const auto *Attr : Builtin->getValueAsListOfDefs(FieldName: "Attributes")) {
450 if (Attr->isSubClassOf(Name: "ArgRange")) {
451 ArgRanges.push_back(Elt: Attr);
452 continue;
453 }
454
455 OS << Attr->getValueAsString(FieldName: "Mangling");
456 if (Attr->isSubClassOf(Name: "IndexedAttribute")) {
457 OS << ':' << Attr->getValueAsInt(FieldName: "Index") << ':';
458 } else if (Attr->isSubClassOf(Name: "MultiIndexAttribute")) {
459 OS << '<';
460 llvm::ListSeparator Sep(",");
461 for (int64_t Index : Attr->getValueAsListOfInts(FieldName: "Indices"))
462 OS << Sep << Index;
463 OS << '>';
464 }
465 }
466
467 // All argument ranges are encoded together as R<Index:Lower:Upper,...>.
468 if (!ArgRanges.empty()) {
469 StringRef Prototype = Builtin->getValueAsString(FieldName: "Prototype").trim();
470 SmallVector<StringRef> Params;
471 if (size_t Open = Prototype.find(C: '('); Open != StringRef::npos)
472 Params = splitParams(Params: Prototype.drop_front(N: Open + 1).drop_back());
473
474 OS << "R<";
475 llvm::ListSeparator Sep(",");
476 SmallDenseSet<int64_t> SeenIndices;
477 for (const Record *Range : ArgRanges) {
478 int64_t Index = Range->getValueAsInt(FieldName: "Index");
479 int64_t Lower = Range->getValueAsInt(FieldName: "Lower");
480 int64_t Upper = Range->getValueAsInt(FieldName: "Upper");
481 if (Index < 0 || Index >= static_cast<int64_t>(Params.size()))
482 PrintFatalError(ErrorLoc: Builtin->getLoc(),
483 Msg: "ArgRange index " + Twine(Index) + " out of bounds");
484
485 if (!Params[Index].starts_with(Prefix: "_Constant"))
486 PrintFatalError(ErrorLoc: Builtin->getLoc(), Msg: "ArgRange argument " + Twine(Index) +
487 " must be _Constant");
488
489 if (!isInt<32>(x: Lower) || !isInt<32>(x: Upper))
490 PrintFatalError(ErrorLoc: Builtin->getLoc(),
491 Msg: "ArgRange bounds must fit in a 32-bit int");
492
493 if (!SeenIndices.insert(V: Index).second)
494 PrintFatalError(ErrorLoc: Builtin->getLoc(),
495 Msg: "duplicate ArgRange for argument " + Twine(Index));
496
497 if (Lower >= Upper)
498 PrintFatalError(ErrorLoc: Builtin->getLoc(), Msg: "ArgRange range is empty");
499
500 OS << Sep << Index << ':' << Lower << ':' << Upper;
501 }
502
503 OS << '>';
504 }
505
506 return Attributes;
507}
508
509Builtin buildBuiltin(StringRef Substitution, const Record *BuiltinRecord,
510 Twine Spelling, BuiltinType BT) {
511 Builtin B;
512 B.BT = BT;
513 B.Name = Spelling.str();
514 B.Type = PrototypeParser(Substitution, BuiltinRecord).takeTypeString();
515 B.Attributes = renderAttributes(Builtin: BuiltinRecord, BT);
516 B.BuiltinRecord = BuiltinRecord;
517 return B;
518}
519
520struct TemplateInsts {
521 std::vector<std::string> Substitution;
522 std::vector<std::string> Affix;
523 bool IsPrefix;
524};
525
526TemplateInsts getTemplateInsts(const Record *R) {
527 TemplateInsts temp;
528 auto Substitutions = R->getValueAsListOfStrings(FieldName: "Substitutions");
529 auto Affixes = R->getValueAsListOfStrings(FieldName: "Affixes");
530 temp.IsPrefix = R->getValueAsBit(FieldName: "AsPrefix");
531
532 if (Substitutions.size() != Affixes.size())
533 PrintFatalError(ErrorLoc: R->getLoc(), Msg: "Substitutions and affixes "
534 "don't have the same lengths");
535
536 for (auto [Affix, Substitution] : zip(t&: Affixes, u&: Substitutions)) {
537 temp.Substitution.emplace_back(args&: Substitution);
538 temp.Affix.emplace_back(args&: Affix);
539 }
540 return temp;
541}
542
543void collectBuiltins(const Record *BuiltinRecord,
544 SmallVectorImpl<Builtin> &Builtins) {
545 TemplateInsts Templates = {};
546 if (BuiltinRecord->isSubClassOf(Name: "Template")) {
547 Templates = getTemplateInsts(R: BuiltinRecord);
548 } else {
549 Templates.Affix.emplace_back();
550 Templates.Substitution.emplace_back();
551 }
552
553 for (auto [Substitution, Affix] :
554 zip(t&: Templates.Substitution, u&: Templates.Affix)) {
555 for (StringRef Spelling :
556 BuiltinRecord->getValueAsListOfStrings(FieldName: "Spellings")) {
557 auto FullSpelling =
558 (Templates.IsPrefix ? Affix + Spelling : Spelling + Affix).str();
559 BuiltinType BT = BuiltinType::Builtin;
560 if (BuiltinRecord->isSubClassOf(Name: "AtomicBuiltin")) {
561 BT = BuiltinType::AtomicBuiltin;
562 } else if (BuiltinRecord->isSubClassOf(Name: "LangBuiltin")) {
563 BT = BuiltinType::LangBuiltin;
564 } else if (BuiltinRecord->isSubClassOf(Name: "TargetLibBuiltin")) {
565 BT = BuiltinType::TargetLibBuiltin;
566 } else if (BuiltinRecord->isSubClassOf(Name: "TargetBuiltin")) {
567 BT = BuiltinType::TargetBuiltin;
568 } else if (BuiltinRecord->isSubClassOf(Name: "LibBuiltin")) {
569 BT = BuiltinType::LibBuiltin;
570 if (BuiltinRecord->getValueAsBit(FieldName: "AddBuiltinPrefixedAlias"))
571 Builtins.push_back(Elt: buildBuiltin(
572 Substitution, BuiltinRecord,
573 Spelling: std::string("__builtin_") + FullSpelling, BT: BuiltinType::Builtin));
574 }
575 Builtins.push_back(
576 Elt: buildBuiltin(Substitution, BuiltinRecord, Spelling: FullSpelling, BT));
577 }
578 }
579}
580} // namespace
581
582void clang::EmitClangBuiltins(const RecordKeeper &Records, raw_ostream &OS) {
583 emitSourceFileHeader(Desc: "List of builtins that Clang recognizes", OS);
584
585 SmallVector<Builtin> Builtins;
586 // AtomicBuiltins are order dependent. Emit them first to make manual checking
587 // easier and so we can build a special atomic builtin X-macro.
588 for (const auto *BuiltinRecord :
589 Records.getAllDerivedDefinitions(ClassName: "AtomicBuiltin"))
590 collectBuiltins(BuiltinRecord, Builtins);
591 unsigned NumAtomicBuiltins = Builtins.size();
592
593 for (const auto *BuiltinRecord :
594 Records.getAllDerivedDefinitions(ClassName: "Builtin")) {
595 if (BuiltinRecord->isSubClassOf(Name: "AtomicBuiltin"))
596 continue;
597 // Prefixed builtins are also special and we emit them last so they can have
598 // their own representation that skips the prefix.
599 if (BuiltinRecord->getValueAsOptionalDef(FieldName: "RequiredNamePrefix"))
600 continue;
601
602 collectBuiltins(BuiltinRecord, Builtins);
603 }
604
605 // Now collect (and count) the prefixed builtins.
606 unsigned NumPrefixedBuiltins = Builtins.size();
607 const Record *FirstPrefix = nullptr;
608 for (const auto *BuiltinRecord :
609 Records.getAllDerivedDefinitions(ClassName: "Builtin")) {
610 auto *Prefix = BuiltinRecord->getValueAsOptionalDef(FieldName: "RequiredNamePrefix");
611 if (!Prefix)
612 continue;
613
614 if (!FirstPrefix)
615 FirstPrefix = Prefix;
616 assert(Prefix == FirstPrefix &&
617 "Multiple distinct prefixes which is not currently supported!");
618 assert(!BuiltinRecord->isSubClassOf("AtomicBuiltin") &&
619 "Cannot require a name prefix for an atomic builtin.");
620 collectBuiltins(BuiltinRecord, Builtins);
621 }
622 NumPrefixedBuiltins = Builtins.size() - NumPrefixedBuiltins;
623
624 auto AtomicBuiltins = ArrayRef(Builtins).slice(N: 0, M: NumAtomicBuiltins);
625 auto UnprefixedBuiltins = ArrayRef(Builtins).drop_back(N: NumPrefixedBuiltins);
626 auto PrefixedBuiltins = ArrayRef(Builtins).take_back(N: NumPrefixedBuiltins);
627
628 // Collect strings into a table.
629 StringToOffsetTable Table;
630 Table.GetOrAddStringOffset(Str: "");
631 for (const auto &B : Builtins) {
632 Table.GetOrAddStringOffset(Str: B.Name);
633 Table.GetOrAddStringOffset(Str: B.Type);
634 Table.GetOrAddStringOffset(Str: B.Attributes);
635 if (B.BT == BuiltinType::TargetBuiltin)
636 Table.GetOrAddStringOffset(Str: B.BuiltinRecord->getValueAsString(FieldName: "Features"));
637 }
638
639 // Emit enumerators.
640 OS << R"c++(
641#ifdef GET_BUILTIN_ENUMERATORS
642)c++";
643 for (const auto &B : Builtins)
644 B.EmitEnumerator(OS);
645 OS << R"c++(
646#endif // GET_BUILTIN_ENUMERATORS
647)c++";
648
649 // Emit a string table that can be referenced for these builtins.
650 OS << R"c++(
651#ifdef GET_BUILTIN_STR_TABLE
652)c++";
653 Table.EmitStringTableDef(OS, Name: "BuiltinStrings");
654 OS << R"c++(
655#endif // GET_BUILTIN_STR_TABLE
656)c++";
657
658 // Emit a direct set of `Builtin::Info` initializers, first for the unprefixed
659 // builtins and then for the prefixed builtins.
660 OS << R"c++(
661#ifdef GET_BUILTIN_INFOS
662)c++";
663 for (const auto &B : UnprefixedBuiltins)
664 B.EmitInfo(OS, Table);
665 OS << R"c++(
666#endif // GET_BUILTIN_INFOS
667)c++";
668
669 OS << R"c++(
670#ifdef GET_BUILTIN_PREFIXED_INFOS
671)c++";
672 for (const auto &B : PrefixedBuiltins)
673 B.EmitInfo(OS, Table);
674 OS << R"c++(
675#endif // GET_BUILTIN_PREFIXED_INFOS
676)c++";
677
678 // Emit X-macros for the atomic builtins to support various custome patterns
679 // used exclusively with those builtins.
680 //
681 // FIXME: We should eventually move this to a separate file so that users
682 // don't need to include the full set of builtins.
683 OS << R"c++(
684#ifdef ATOMIC_BUILTIN
685)c++";
686 for (const auto &Builtin : AtomicBuiltins) {
687 Builtin.EmitXMacro(OS);
688 }
689 OS << R"c++(
690#endif // ATOMIC_BUILTIN
691#undef ATOMIC_BUILTIN
692)c++";
693}
694
695//===----------------------------------------------------------------------===//
696// Builtin documentation emitter
697//===----------------------------------------------------------------------===//
698
699/// Holds the data needed to emit documentation for a single builtin.
700namespace {
701struct BuiltinDocData {
702 const Record *Documentation = nullptr;
703 const Record *BuiltinRecord = nullptr;
704 std::string Heading;
705
706 BuiltinDocData(const Record *D, const Record *B)
707 : Documentation(D), BuiltinRecord(B) {
708 // Use the Heading field if set, otherwise use the builtin's first
709 // spelling.
710 StringRef HeadingStr = D->getValueAsString(FieldName: "Heading");
711 if (HeadingStr.empty()) {
712 std::vector<StringRef> Spellings =
713 B->getValueAsListOfStrings(FieldName: "Spellings");
714 if (!Spellings.empty())
715 Heading = Spellings[0].str();
716 else
717 Heading = B->getName().str();
718 } else {
719 Heading = HeadingStr.str();
720 }
721 }
722};
723} // namespace
724
725static void writeCategoryHeader(const Record *Category, raw_ostream &OS) {
726 StringRef CategoryName = Category->getValueAsString(FieldName: "Name");
727 OS << "\n" << CategoryName << "\n";
728 for (size_t I = 0, E = CategoryName.size(); I < E; ++I)
729 OS << "=";
730 OS << "\n\n";
731
732 StringRef CategoryContent = Category->getValueAsString(FieldName: "Content");
733 if (!CategoryContent.trim().empty())
734 OS << CategoryContent.trim() << "\n\n";
735}
736
737static void writeBuiltinDocumentation(const BuiltinDocData &Doc,
738 raw_ostream &OS) {
739 // Write heading with '-' underline (subsection).
740 std::string HeadingText = "``" + Doc.Heading + "``";
741 OS << HeadingText << "\n";
742 for (size_t I = 0, E = HeadingText.size(); I < E; ++I)
743 OS << "-";
744 OS << "\n\n";
745
746 // Write prototype as a code block.
747 StringRef Prototype = Doc.BuiltinRecord->getValueAsString(FieldName: "Prototype");
748 if (!Prototype.empty()) {
749 std::vector<StringRef> Spellings =
750 Doc.BuiltinRecord->getValueAsListOfStrings(FieldName: "Spellings");
751 StringRef Name =
752 Spellings.empty() ? Doc.BuiltinRecord->getName() : Spellings[0];
753
754 // Split prototype into return type and params at the first '('.
755 size_t ParenPos = Prototype.find(C: '(');
756 if (ParenPos != StringRef::npos) {
757 StringRef RetType = Prototype.substr(Start: 0, N: ParenPos).rtrim();
758 StringRef ParamStr =
759 Prototype.substr(Start: ParenPos + 1, N: Prototype.size() - ParenPos - 2);
760
761 OS << "**Prototype:**\n\n";
762 OS << ".. code-block:: c\n\n";
763 OS << " " << RetType << " " << Name << "(";
764
765 std::vector<StringRef> ArgNames =
766 Doc.BuiltinRecord->getValueAsListOfStrings(FieldName: "ArgNames");
767 if (!ArgNames.empty()) {
768 SmallVector<StringRef> ParamTypes = splitParams(Params: ParamStr);
769 bool IsVariadic = !ParamTypes.empty() && ParamTypes.back() == "...";
770 size_t NamedParams = ParamTypes.size() - (IsVariadic ? 1 : 0);
771 if (ArgNames.size() != NamedParams)
772 PrintFatalError(ErrorLoc: Doc.BuiltinRecord->getLoc(),
773 Msg: "number of ArgNames (" + Twine(ArgNames.size()) +
774 ") does not match number of prototype "
775 "parameters (" +
776 Twine(NamedParams) + ")");
777 for (size_t I = 0, E = ParamTypes.size(); I < E; ++I) {
778 if (I > 0)
779 OS << ", ";
780 if (I < NamedParams)
781 OS << ParamTypes[I] << " " << ArgNames[I];
782 else
783 OS << ParamTypes[I];
784 }
785 } else {
786 OS << ParamStr;
787 }
788
789 OS << ")\n\n";
790 }
791 }
792
793 // Write target features if this is a TargetBuiltin with features.
794 if (Doc.BuiltinRecord->isSubClassOf(Name: "TargetBuiltin")) {
795 StringRef Features = Doc.BuiltinRecord->getValueAsString(FieldName: "Features");
796 if (!Features.empty())
797 OS << "**Target Features:** " << Features << "\n\n";
798 }
799
800 // Write documentation content.
801 StringRef Content = Doc.Documentation->getValueAsString(FieldName: "Content");
802 OS << Content.trim() << "\n\n\n";
803}
804
805void clang::EmitClangBuiltinDocs(const RecordKeeper &Records, raw_ostream &OS) {
806 // Get the documentation introduction paragraph.
807 const Record *Doc = Records.getDef(Name: "GlobalDocumentation");
808 if (!Doc) {
809 PrintFatalError(Msg: "The GlobalDocumentation top-level definition is missing, "
810 "no documentation will be generated.");
811 }
812
813 OS << Doc->getValueAsString(FieldName: "Intro") << "\n";
814
815 // Gather documentation from each builtin, grouped by category.
816 llvm::MapVector<const Record *, std::vector<BuiltinDocData>> SplitDocs;
817
818 for (const Record *B : Records.getAllDerivedDefinitions(ClassName: "Builtin")) {
819 for (const Record *D : B->getValueAsListOfDefs(FieldName: "Documentation")) {
820 const Record *Category = D->getValueAsDef(FieldName: "Category");
821 StringRef Cat = Category->getValueAsString(FieldName: "Name");
822 // Skip builtins that are explicitly internal-only.
823 if (Cat == "InternalOnly")
824 continue;
825 SplitDocs[Category].emplace_back(args&: D, args&: B);
826 }
827 }
828
829 // Sort categories alphabetically by name for deterministic output, but
830 // push the "Undocumented" category to the end so that documented sections
831 // always appear first.
832 llvm::sort(C&: SplitDocs, Comp: [](const auto &A, const auto &B) {
833 StringRef NameA = A.first->getValueAsString("Name");
834 StringRef NameB = B.first->getValueAsString("Name");
835 bool UndocA = (NameA == "Undocumented");
836 bool UndocB = (NameB == "Undocumented");
837 if (UndocA != UndocB)
838 return UndocB;
839 return NameA < NameB;
840 });
841
842 // Write out each category and its builtins.
843 for (auto &[Category, Docs] : SplitDocs) {
844 writeCategoryHeader(Category, OS);
845
846 // Sort entries alphabetically by heading.
847 llvm::sort(C&: Docs, Comp: [](const BuiltinDocData &A, const BuiltinDocData &B) {
848 return A.Heading < B.Heading;
849 });
850
851 for (const BuiltinDocData &D : Docs)
852 writeBuiltinDocumentation(Doc: D, OS);
853 }
854}
855