Documenting Clang intrinsic functions

Clang Frontend
,
1

I’ve noticed that we don’t have documentation explaining what our intrinsics do. As best I can tell, the operations mentioned in this list map to the corresponding names found in Other Built-in Functions Provided by GCC.

If this is an accurate conclusion (supported by my usage of __builtin_popcount and __builtin_clz), then I’ll try to come up with some documentation that describes these in the near future.

1 Like
2

There is documentation for some of them. Really these documents should be generated from tablegen with doc strings attached to the definitions

1 Like
3

On a similar note, the LLVM intrinsic documentation should probably also be autogenerated from tablegen.

There’s precedent for autogenerating documentation from tablegen for clang attributes (include/clang/Basic/AttrDocs.td) and driver options (include/clang/Driver/ClangOptionDocs.td). I have a mind to build something like that for LLVM intrinsics, and clang builtins can certainly partially leverage that documentation as well (as several clang builtins are also LLVM intrinsics), but I haven’t had any time to do more than think about it.

1 Like
4

Good point; a TableGen-based approach would be the best way to achieve this. If it’s like AttrDocs.td, I can’t imagine it taking too much time to do?

1 Like
5

One of my favourite examples for using TableGen for documentation and generating C++ code:
https://flang.llvm.org/docs/FIRLangRef.html

6

I like this approach, it would ensure that the documentation doesn’t get out of sync again

7

I think that’s a great idea – it’s worked really well for attributes and command line options, and it especially helps reviewers to notice when documentation is missing for a new change.

8

Let’s be sure to make a distinction between the builtins which are defined in TableGen files and (yes) built-in to the compiler, versus intrinsic functions which are defined in the header files maintained in clang/lib/Headers (and which commonly invoke builtin functions to achieve their effect). Documentation for the latter is in the header files themselves. (I’ll be adding documentation to a chunk of X86 intrinsics in the Headers in the near future.)

I’ll also note that there have been efforts in the past to improve instruction selection to the point of being able to eliminate bunches of target-specific builtins, and rewrite the intrinsics in Headers to use normal expressions rather than invoking builtins.