[PATCH] D63040: [Docs] [llvm-mca] Point out a caveat for using llvm-mca markers in source code.

[Max Marrone via Phabricator via llvm-commits]

Maxpm marked an inline comment as done.
Maxpm added inline comments.


================
Comment at: llvm/docs/CommandGuide/llvm-mca.rst:265-269
+It is generally safe to use source-level markers in straight-line source code without
+any control flow, like the example above.  Otherwise, you must take care to make
+sure that the code you are analyzing is the same as the code the compiler actually
+wants to generate.  Unfortunately, the only robust way to do this is to manually
+add the markers to the assembly text.
----------------
andreadb wrote:
> The impact of source level markers on the compiler generated code is not quantifiable. It really depends on a number of things. So we shouldn't claim that there are cases where it is generally safe. It is misleading and inaccurate at best.
> 
> Even wanting to keep that first statement, it is unclear what you meant by "source-level markers in straight-line source code without any control flow". That is going to cause a lot of confusion to the reader (which knows already that a code sequence should never span through multiple basic blocks) and we don't want that.
> 
> Strictly speaking, the entire paragraph can be summarized as "use markers at your own risk", which is clearly already impled by your previous paragraph. So, to be honest it is a bit of a repetition.
> In my opinion you should remove this entire paragraph, as it is redundant.
> The impact of source level markers on the compiler generated code is not quantifiable...So we shouldn't claim that there are cases where it is generally safe.

Yes, I see your point.  If we don't suggest safe source constructions, could we at least suggest checking out the `-Rpass-missed` options so the user could double-check for herself?  Or do you think even that is too unreliable?

Basically, I'm worried that the docs introduce this feature only to immediately and totally disavow it.  If there's really no way to use it properly, should we be telling people how to use it at all?  Then again, inline asm statements are something that someone could plausibly come up with on their own, so they should be warned of the gotcha....

> the reader (which knows already that a code sequence should never span through multiple basic blocks)

Do they?  I can't find that explicitly said in the docs anywhere, and the tool only warns when it finds a `ret` instruction.  That might be worth another patch?


Repository:
  rL LLVM

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D63040/new/

https://reviews.llvm.org/D63040