Update docs about [[likely]] vs. PGO

[hans]

Summary

It sounds like these attributes do nothing when PGO is enabled, which is actually (or please correct me if I'm wrong) only the case when there is profile data coverage the specific statements in question. If there is no profile data, the attributes still apply.

[serge-sans-paille]

While running this small experiment: https://sergesanspaille.fedorapeople.org/proftest.sh
I get the following output:

clang version 16.0.0 (...)
Target: x86_64-unknown-linux-gnu
Thread model: posix
InstalledDir: ...
==== - instrumentation + likely: puts first

00000000000006d0 <main>:
 6d0:	50                   	push   %rax
 6d1:	83 ff 01             	cmp    $0x1,%edi
 6d4:	75 10                	jne    6e6 <main+0x16>
 6d6:	48 8d 3d a7 00 00 00 	lea    0xa7(%rip),%rdi        # 784 <_IO_stdin_used+0x4>
 6dd:	e8 ce fe ff ff       	callq  5b0 <puts@plt>
 6e2:	31 c0                	xor    %eax,%eax
 6e4:	59                   	pop    %rcx
 6e5:	c3                   	retq   
 6e6:	48 8b 06             	mov    (%rsi),%rax
 6e9:	48 8b 56 08          	mov    0x8(%rsi),%rdx
 6ed:	48 8d 3d 9b 00 00 00 	lea    0x9b(%rip),%rdi        # 78f <_IO_stdin_used+0xf>
 6f4:	48 89 c6             	mov    %rax,%rsi
 6f7:	31 c0                	xor    %eax,%eax
 6f9:	e8 92 fe ff ff       	callq  590 <printf@plt>
 6fe:	eb e2                	jmp    6e2 <main+0x12>

0000000000000700 <__libc_csu_init>:

====  + instrumentation + likely: puts first

00000000000005e0 <main>:
 5e0:	50                   	push   %rax
 5e1:	83 ff 01             	cmp    $0x1,%edi
 5e4:	75 10                	jne    5f6 <main+0x16>
 5e6:	48 8d 3d 97 01 00 00 	lea    0x197(%rip),%rdi        # 784 <_IO_stdin_used+0x4>
 5ed:	e8 be ff ff ff       	callq  5b0 <puts@plt>
 5f2:	31 c0                	xor    %eax,%eax
 5f4:	59                   	pop    %rcx
 5f5:	c3                   	retq   
 5f6:	48 8b 06             	mov    (%rsi),%rax
 5f9:	48 8b 56 08          	mov    0x8(%rsi),%rdx
 5fd:	48 8d 3d 8b 01 00 00 	lea    0x18b(%rip),%rdi        # 78f <_IO_stdin_used+0xf>
 604:	48 89 c6             	mov    %rax,%rsi
 607:	31 c0                	xor    %eax,%eax
 609:	e8 82 ff ff ff       	callq  590 <printf@plt>
 60e:	eb e2                	jmp    5f2 <main+0x12>

0000000000000610 <_start>:
./b1.out 12
==== - instrumentation - likely: puts first

00000000000006d0 <main>:
 6d0:	50                   	push   %rax
 6d1:	83 ff 01             	cmp    $0x1,%edi
 6d4:	75 0e                	jne    6e4 <main+0x14>
 6d6:	48 8d 3d a7 00 00 00 	lea    0xa7(%rip),%rdi        # 784 <_IO_stdin_used+0x4>
 6dd:	e8 ce fe ff ff       	callq  5b0 <puts@plt>
 6e2:	eb 18                	jmp    6fc <main+0x2c>
 6e4:	48 8b 06             	mov    (%rsi),%rax
 6e7:	48 8b 56 08          	mov    0x8(%rsi),%rdx
 6eb:	48 8d 3d 9d 00 00 00 	lea    0x9d(%rip),%rdi        # 78f <_IO_stdin_used+0xf>
 6f2:	48 89 c6             	mov    %rax,%rsi
 6f5:	31 c0                	xor    %eax,%eax
 6f7:	e8 94 fe ff ff       	callq  590 <printf@plt>
 6fc:	31 c0                	xor    %eax,%eax
 6fe:	59                   	pop    %rcx
 6ff:	c3                   	retq   

0000000000000700 <__libc_csu_init>:

====  + instrumentation - likely: printf first

00000000000005e0 <main>:
 5e0:	50                   	push   %rax
 5e1:	83 ff 01             	cmp    $0x1,%edi
 5e4:	74 1c                	je     602 <main+0x22>
 5e6:	48 8b 06             	mov    (%rsi),%rax
 5e9:	48 8b 56 08          	mov    0x8(%rsi),%rdx
 5ed:	48 8d 3d 9b 01 00 00 	lea    0x19b(%rip),%rdi        # 78f <_IO_stdin_used+0xf>
 5f4:	48 89 c6             	mov    %rax,%rsi
 5f7:	31 c0                	xor    %eax,%eax
 5f9:	e8 92 ff ff ff       	callq  590 <printf@plt>
 5fe:	31 c0                	xor    %eax,%eax
 600:	59                   	pop    %rcx
 601:	c3                   	retq   
 602:	48 8d 3d 7b 01 00 00 	lea    0x17b(%rip),%rdi        # 784 <_IO_stdin_used+0x4>
 609:	e8 a2 ff ff ff       	callq  5b0 <puts@plt>
 60e:	eb ee                	jmp    5fe <main+0x1e>

0000000000000610 <_start>:

To me, it means that [[likely]] takes precedence over profile information...

[aaron.ballman]

In D134394#3808397, @serge-sans-paille wrote:

While running this small experiment: https://sergesanspaille.fedorapeople.org/proftest.sh

Thank you for the help with testing the assumptions here!

[hans]

See also D134456 which affects the behavior here.

clang/include/clang/Basic/AttrDocs.td

 or the ``default`` label with the same likelihood attribute. This makes
 * all labels without an attribute have a neutral likelihood,
 * all labels marked ``[[likely]]`` have an equally positive likelihood, and
 * all labels marked ``[[unlikely]]`` have an equally negative likelihood.
 The neutral likelihood is the more likely of path execution than the negative
 likelihood. The positive likelihood is the more likely of path of execution
 than the neutral likelihood.
 
-These attributes have no effect on the generated code when using
-PGO (Profile-Guided Optimization) or at optimization level 0.
+These attributes have no effect on the generated code when there is PGO
+(Profile-Guided Optimization) data available for the statements, or at
+optimization level 0.
 
 In Clang, the attributes will be ignored if they're not placed on
 * the ``case`` or ``default`` label of a ``switch`` statement,
 * or on the substatement of an ``if`` or ``else`` statement,
 * or on the substatement of an ``for`` or ``while`` statement.
 The C++ Standard recommends to honor them on every statement in the
 path of execution, but that can be confusing: