Document and test __builtin_expect_with_probability.

2019-07-09  Martin Liska  <mliska@suse.cz>

	* doc/extend.texi: Document influence on loop
	optimizers.
2019-07-09  Martin Liska  <mliska@suse.cz>

	* gcc.dg/predict-17.c: Test loop optimizer assumption
	about loop iterations.

From-SVN: r273295

gcc/ChangeLog

@@ -8,6 +8,11 @@
 
 2019-07-09  Martin Liska  <mliska@suse.cz>
 
+	* doc/extend.texi: Document influence on loop
+	optimizers.
+
+2019-07-09  Martin Liska  <mliska@suse.cz>
+
 	* lto-compress.c (lto_normalized_zstd_level): Do not use
 	ZSTD_CLEVEL_DEFAULT as it is not default in old releases
 	of libzstd.  One can use 0 as a default compression level.

gcc/doc/extend.texi

@@ -13045,8 +13045,11 @@ when testing pointer or floating-point values.
 For the purposes of branch prediction optimizations, the probability that
 a @code{__builtin_expect} expression is @code{true} is controlled by GCC's
 @code{builtin-expect-probability} parameter, which defaults to 90%.  
+
 You can also use @code{__builtin_expect_with_probability} to explicitly 
-assign a probability value to individual expressions.
+assign a probability value to individual expressions.  If the built-in
+is used in a loop construct, the provided probability will influence
+the expected number of iterations made by loop optimizations.
 @end deftypefn
 
 @deftypefn {Built-in Function} long __builtin_expect_with_probability

gcc/testsuite/ChangeLog

+2019-07-09  Martin Liska  <mliska@suse.cz>
+
+	* gcc.dg/predict-17.c: Test loop optimizer assumption
+	about loop iterations.
+
 2019-07-09  Richard Biener  <rguenther@suse.de>
 
 	* gcc.dg/tree-ssa/alias-access-path-1.c: Scan fre1 dump.

gcc/testsuite/gcc.dg/predict-17.c

 /* { dg-do compile } */
-/* { dg-options "-O2 -fdump-tree-profile_estimate" } */
+/* { dg-options "-O2 -fdump-tree-profile_estimate-details" } */
 
 extern int global;
 
@@ -11,3 +11,5 @@ void foo (int base)
 
 /* { dg-final { scan-tree-dump "first match heuristics: 5.00%" "profile_estimate"} } */
 /* { dg-final { scan-tree-dump "__builtin_expect_with_probability heuristics of edge .*->.*: 5.00%" "profile_estimate"} } */
+/* { dg-final { scan-tree-dump "is probably executed at most 19" "profile_estimate"} } */
+