Document optimization flags

[Quuxplusone]

Bugzilla Link	PR20543
Status	NEW
Importance	P enhancement
Reported by	Gonzalo BG (gonzalo.gadeschi@gmail.com)
Reported on	2014-08-05 06:25:36 -0700
Last modified on	2014-08-06 12:26:25 -0700
Version	trunk
Hardware	All All
CC	llvm-bugs@lists.llvm.org, paul_robinson@playstation.sony.com, rnk@google.com, silvasean@google.com
Fixed by commit(s)
Attachments
Blocks
Blocked by
See also

I have tried to find documentation about the optimization flags available
in the current version of clang (ToT) without much success (both in the
webpage, the manual, and google).  Google always points me to:
http://clang.llvm.org/docs/UsersManual.html but I see no information there
regarding optimization levels/flags.

I'm particularly interested in:

- which optimization flags are there and a description of what they do
(e.g. -ffast-math),

- which optimization levels are there (e.g. O2) and which flags does each
level enable,

- which potentially-useful but unstable/not supported llvm optimization options
are there (e.g. -mllvm -inline-threshold=value has a large impact on
performance [0]) and a link to the llvm docs that describe them.

I asked this in the mailing list [1] but no answers so far. Anyhow, even if
this is already documented somewhere it should be easier to find than it is now.

[0] http://www.reddit.com/r/cpp/comments/24663s/range_comprehensions/ch46dye
[1] http://lists.cs.uiuc.edu/pipermail/cfe-users/2014-July/000541.html

[Quuxplusone]

It would also be nice to know:

• which optimization flags are there for gcc compatibility only but do nothing.

[Quuxplusone]

We generally only have high-level optimization flags, like -flto, -O, -ffast-math, and -fstrict-aliasing. We could document these. I don't think we will ever document options in -mllvm, though.

[Quuxplusone]

Any documentation about the available flags would be greatly appreciated. For instance I'm also using -march=native, -mtune=native, -pipe, -fdata-sections, -ffunction-sections, -fvectorize, and -fslp-vectorize-aggressive (and well -DNDEBUG..) but I don't know if these flags do anything or if there are other flags that I should be using instead.

A bonus would be including a section about other flags that you can tune through the clang front-end (like potentially useful llvm flags) and to forward the user to the corresponding documentation (e.g. llvm docs). I think that a list of these options is very valuable and can save a lot of time to some users willing to go this far. In the previously mentioned "micro benchmark" tunning -mllvm -inline-threshold reduced execution time by 4x...

[Quuxplusone]

(In reply to comment #3)
> Any documentation about the available flags would be greatly appreciated.
> For instance I'm also using -march=native, -mtune=native, -pipe,
> -fdata-sections, -ffunction-sections, -fvectorize, and
> -fslp-vectorize-aggressive (and well -DNDEBUG..) but I don't know if these
> flags do anything or if there are other flags that I should be using
> instead.

These flags do wildly different things. Some don't even affect the execution
speed of the compiled program (e.g. -pipe, which theoretically just affects how
the sub-tasks of the compiler driver communicate with each other). Things like -
DNDEBUG isn't even an "optimization command line option", it's just -D for a
macro of special significance.

It seems like what you are asking for is more "everything I can possibly tweak
on the compiler command line to see if it affects performance". Is that correct?

>
> A bonus would be including a section about other flags that you can tune
> through the clang front-end (like potentially useful llvm flags) and to
> forward the user to the corresponding documentation (e.g. llvm docs). I
> think that a list of these options is very valuable and can save a lot of
> time to some users willing to go this far. In the previously mentioned
> "micro benchmark" tunning -mllvm -inline-threshold reduced execution time by
> 4x...

-mllvm is special in that it essentially passes command line options directly
to the LLVM optimizer, which is unstable and should not be relied upon for
backwards compatibility! If you really want to know the options it accepts then
look at what the opt tool accepts. If a user is really "willing to go this far"
then they should use clang's -emit-llvm option and do their optimization
through opt. (NOT RECOMMENDED!)

[Quuxplusone]

These flags do wildly different things. Some don't even affect the execution speed of the compiled program (e.g. -pipe, which theoretically just affects how the sub-tasks of the compiler driver communicate with each other).

This is exactly why I think they should be documented somewhere. There is a lot of misconceptions about them.

It seems like what you are asking for is more "everything I can possibly tweak on the compiler command line to see if it affects performance". Is that correct?

I'm asking here is for a page listing all optimization-related flags. A page listing all flags that the compiler can take (e.g. not only those that are optimization related) would also be valuable (e.g. for things like -pipe). And of course, a page about "everything I can possibly tweak on the compiler command line" that might affect performance would be also valuable.

Things like -DNDEBUG isn't even an "optimization command line option", it's just -D for a macro of special significance.

Yes. There is no place for it on a page documenting the optimization-related flags of a compiler but it should be in a page about "everything I can possibly tweak on the compiler command line that might affect performance".

-mllvm is special in that it essentially passes command line options directly to the LLVM optimizer, which is unstable and should not be relied upon for backwards compatibility! If you really want to know the options it accepts then look at what the opt tool accepts. If a user is really "willing to go this far" then they should use clang's -emit-llvm option and do their optimization through opt. (NOT RECOMMENDED!)

Just mentioning that one can pass flags to the LLVM optimizer directly and linking its documentation (or the documentation of its flags) should be enough. One should definitely mention that tinkering with these is not recommended for the reasons you mention above. In a page about "everything I can possibly tweak" one could mention some of them but keeping these in sync with the LLVM optimizer docs is too much work (users can go to their docs directly as you said).

[Quuxplusone]

(In reply to comment #5)
> >These flags do wildly different things. Some don't even affect the execution
speed of the compiled program (e.g. -pipe, which theoretically just affects how
the sub-tasks of the compiler driver communicate with each other).
>
> This is exactly why I think they should be documented somewhere. There is a
> lot of misconceptions about them.

Can you give a concrete example? Does anybody have the misconception that -pipe
will make their program faster?

>
> > It seems like what you are asking for is more "everything I can possibly
tweak on the compiler command line to see if it affects performance". Is that
correct?
>
> I'm asking here is for a page listing all optimization-related flags.

Ok, that sounds doable. Can you start a discussion on cfe-dev to refine exactly
what will go in the document? There are some options like -fassume-sane-
operator-new that can affect performance but don't affect the optimizer per se
(that is, it just controls the behavior of the frontend and the IR it
generates, but doesn't actually configure the optimizer differently).

>  A page
> listing all flags that the compiler can take (e.g. not only those that are
> optimization related) would also be valuable (e.g. for things like -pipe).
> And of course, a page about "everything I can possibly tweak on the compiler
> command line" _that might affect performance_ would be also valuable.
>
> > Things like -DNDEBUG isn't even an "optimization command line option", it's
just -D for a macro of special significance.
>
> Yes. There is no place for it on a page documenting the optimization-related
> flags of a compiler but it should be in a page about "everything I can
> possibly tweak on the compiler command line that might affect performance".

There isn't really a good place for that in our docs, since usually such macros
affect things that are not part of the compiler (e.g. they opt into a faster
but backwards-incompatible implementation of some aspect of the standard
library).

I personally think its a bit silly to document -DNDEBUG since we can assume
that the user already knows about this and aren't tweaking performance on
+Asserts builds.

I can't really think what a page "everything I can possibly tweak on the
compiler command line that might affect performance" would have besides the
relevant optimization flags (which you are proposing as a page by itself), so
I'm not sure sure a "everything I can possibly tweak on the compiler command
line that might affect performance" page even makes sense.

>
> >-mllvm is special in that it essentially passes command line options
directly to the LLVM optimizer, which is unstable and should not be relied upon
for backwards compatibility! If you really want to know the options it accepts
then look at what the opt tool accepts. If a user is really "willing to go this
far" then they should use clang's -emit-llvm option and do their optimization
through opt. (NOT RECOMMENDED!)
>
> Just mentioning that one can pass flags to the LLVM optimizer directly and
> linking its documentation (or the documentation of its flags) should be
> enough. One should definitely mention that tinkering with these is not
> recommended for the reasons you mention above. In a page about "everything I
> can possibly tweak" one could mention some of them but keeping these in sync
> with the LLVM optimizer docs is too much work (users can go to their docs
> directly as you said).

There isn't anywhere to link to though, as these flags are not documented
anywhere since they are in general implementation details (actually the fact
that inline-threshold is set globally with a flag could be considered a bug;
this behavior is fundamentally at odds with the design of LLVM's optimizer).