TableGen docs

Project Infrastructure LLVM Dev List Archives
1

Hi folks,

It took a while, but I finally have some bandwidth to look at this.

I've been reading the two existing TableGen documents:

http://llvm.org/docs/TableGenFundamentals.html
http://llvm.org/docs/TableGen/LangRef.html

the first is linked from the index, but LangRef is not (though it has
some remains in the metadata). I'm wondering what's the relationship
between them two.

My plan is to have three docs:

1. What is TableGen; No info about language, back-ends but just a
rough idea on when it's used (build-time), why it's used (meta-code),
where (a list of back-ends with a simple description) and which
additional cases could be covered by the current implementation.

2. TableGen back-ends; a list of all back-ends in use today, what are
their purposes, why they differ and some inner secrets of their
implementation. This page could also have a tutorial on how to create
a new back-end, though this could be in a separate doc.

3. TableGen's language reference; Similar to most of fundamentals' and
LangRef's contents, only focusing on syntax.

Aditional pages:

* Deficiencies and plans to overcome them
* How to create a new back-end

All pages should be inside the TableGen directory with its own index.

I'll create the docs but won't link them from the main index, so that
if I get it completely wrong, people won't get the wrong idea. Once
it's better than the original, we can switch and continue.

Does that sound like a good plan?

cheers,
--renato

2

Would it also make sense to include the clang usages of tablegen
somewhere in #1, and then perhaps have #2.5 about clang usages (not
volunteering you for that work btw)? Diagnostics and attributes make
heavy use of tablegen in clang, for instance.

~Aaron

3

I meant to ask about this... Clang has a huge list of back-ends and
they seem extremely similar to each other. Is there any reason why
this is necessary, is this some deficiency in how the TableGen engine
runs, or was it just the simplest way to add functionality?

I agree it'd be good to have both LLVM and Clang usages.

cheers,
--renato

4

Would it also make sense to include the clang usages of tablegen
somewhere in #1, and then perhaps have #2.5 about clang usages (not
volunteering you for that work btw)? Diagnostics and attributes make
heavy use of tablegen in clang, for instance.

I meant to ask about this... Clang has a huge list of back-ends and
they seem extremely similar to each other. Is there any reason why
this is necessary, is this some deficiency in how the TableGen engine
runs, or was it just the simplest way to add functionality?

Some of it has to do with layering. For instance, many of the
attribute tablegen backends exist because they generate .inc files for
the lexer, the parser, sema, etc.

Some of it has to do with what's being generated -- sometimes it's a
.inc file with complete implementations of functionality, other times
it's a .inc file with just some StringSwitch .Case statements, etc.

Some of it is likely simple misunderstanding of what can be done. :slight_smile:
I would love to consolidate some more of the clang tablegen backends
(I already did this with the StringSwitch cases where possible).

I agree it'd be good to have both LLVM and Clang usages.

Awesome! And btw, since I kind of failed to mention it before: your
plan looks good to me, and thanks for working on it!

~Aaron

5

Folks,

The docs are now live, but not linked from the main page yet, so
nothing is visible from a user point of view, but we can already edit
and cross-check each others' work live.

http://llvm.org/docs/TableGen/

Note that this also includes (for now at least) the Clang back-ends
sections. We may split it later, but for now, I'd like to keep them
together to facilitate editing and commenting.

Please, add your part on what you know, which back-end you
implemented, why, etc.

thanks!
--renato

6

This is great, thanks Renato!

Eli

7

Agreed. Absolutely fantastic to see this happening.

-jim

8

Aaron,

I've added short descriptions for most LLVM back-ends, with the files
they create, what's in them and who uses them.

http://llvm.org/docs/TableGen/BackEnds.html

I did this by scanning the build logs, inc files and greping them in
the cpp/h files in lib/Target. There is no information at all on the
intention of each back-end, but not all of them need it. Feel free to
add more stuff to the LLVM, and if you know about the Clang part,
please complete it. :wink:

Once that's reasonably complete, we should change the link in the
index to TableGen/index.html and remove TableGenFundamentals.html.

cheers,
--renato

9

Great work!

I added some very nascent information about the clang attribute
backends in r204635. As I have the time, I'll go back and flesh them
out a bit further.

~Aaron

10

Sorry for the insanely late reply.

This all looks great. Thanks for all the hard work!

– Sean Silva