From 6bb4268527df596e72a964f94873162b595fb483 Mon Sep 17 00:00:00 2001 From: Martin Sebor Date: Thu, 13 Dec 2018 22:52:19 +0000 Subject: [PATCH] extend.texi: Consistently use @code for const and volatile qualifiers... gcc/ChangeLog: * doc/extend.texi: Consistently use @code for const and volatile qualifiers, the true and false constants, and asm statements. From-SVN: r267111 --- gcc/ChangeLog | 5 ++ gcc/doc/extend.texi | 221 ++++++++++++++++++++++++++++------------------------ 2 files changed, 125 insertions(+), 101 deletions(-) diff --git a/gcc/ChangeLog b/gcc/ChangeLog index 2029c98..98c6fc0 100644 --- a/gcc/ChangeLog +++ b/gcc/ChangeLog @@ -1,3 +1,8 @@ +2018-12-13 Martin Sebor + + * doc/extend.texi: Consistently use @code for const and volatile + qualifiers, the true and false constants, and asm statements. + 2018-12-13 Vladimir Makarov PR rtl-optimization/88414 diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi index 4fc72d7..3889ecb 100644 --- a/gcc/doc/extend.texi +++ b/gcc/doc/extend.texi @@ -8483,7 +8483,8 @@ All basic @code{asm} blocks are implicitly volatile. @item inline If you use the @code{inline} qualifier, then for inlining purposes the size -of the asm is taken as the smallest size possible (@pxref{Size of an asm}). +of the @code{asm} statement is taken as the smallest size possible (@pxref{Size +of an asm}). @end table @subsubheading Parameters @@ -8629,7 +8630,8 @@ qualifier to disable certain optimizations. @xref{Volatile}. @item inline If you use the @code{inline} qualifier, then for inlining purposes the size -of the asm is taken as the smallest size possible (@pxref{Size of an asm}). +of the @code{asm} statement is taken as the smallest size possible +(@pxref{Size of an asm}). @item goto This qualifier informs the compiler that the @code{asm} statement may @@ -8741,7 +8743,7 @@ void DoCheck(uint32_t dwSomeValue) The next example shows a case where the optimizers can recognize that the input (@code{dwSomeValue}) never changes during the execution of the function and can therefore move the @code{asm} outside the loop to produce more efficient code. -Again, using @code{volatile} disables this type of optimization. +Again, using the @code{volatile} qualifier disables this type of optimization. @example void do_print(uint32_t dwSomeValue) @@ -8797,20 +8799,21 @@ GCC's optimizers do not treat this code like the non-volatile code in the earlier examples. They do not move it out of loops or omit it on the assumption that the result from a previous call is still valid. -Note that the compiler can move even volatile @code{asm} instructions relative +Note that the compiler can move even @code{volatile asm} instructions relative to other code, including across jump instructions. For example, on many targets there is a system register that controls the rounding mode of -floating-point operations. Setting it with a volatile @code{asm}, as in the -following PowerPC example, does not work reliably. +floating-point operations. Setting it with a @code{volatile asm} statement, +as in the following PowerPC example, does not work reliably. @example asm volatile("mtfsf 255, %0" : : "f" (fpenv)); sum = x + y; @end example -The compiler may move the addition back before the volatile @code{asm}. To -make it work as expected, add an artificial dependency to the @code{asm} by -referencing a variable in the subsequent code, for example: +The compiler may move the addition back before the @code{volatile asm} +statement. To make it work as expected, add an artificial dependency to +the @code{asm} by referencing a variable in the subsequent code, for +example: @example asm volatile ("mtfsf 255,%1" : "=X" (sum) : "f" (fpenv)); @@ -8819,7 +8822,7 @@ sum = x + y; Under certain circumstances, GCC may duplicate (or remove duplicates of) your assembly code when optimizing. This can lead to unexpected duplicate symbol -errors during compilation if your asm code defines symbols or labels. +errors during compilation if your @code{asm} code defines symbols or labels. Using @samp{%=} (@pxref{AssemblerTemplate}) may help resolve this problem. @@ -8848,7 +8851,7 @@ that some assembler dialects use semicolons to start a comment. Do not expect a sequence of @code{asm} statements to remain perfectly consecutive after compilation, even when you are using the @code{volatile} qualifier. If certain instructions need to remain consecutive in the output, -put them in a single multi-instruction asm statement. +put them in a single multi-instruction @code{asm} statement. Accessing data from C programs without using input/output operands (such as by using global symbols directly from the assembler template) may not work as @@ -9041,7 +9044,8 @@ The code generated by GCC to access the memory address in @var{b} can contain registers which @emph{might} be shared by @var{a}, and GCC considers those registers to be inputs to the asm. As above, GCC assumes that such input registers are consumed before any outputs are written. This assumption may -result in incorrect behavior if the asm writes to @var{a} before using +result in incorrect behavior if the @code{asm} statement writes to @var{a} +before using @var{b}. Combining the @samp{&} modifier with the register constraint on @var{a} ensures that modifying @var{a} does not affect the address referenced by @var{b}. Otherwise, the location of @var{b} @@ -9123,8 +9127,8 @@ for @code{d} by specifying both constraints. Some targets have a special register that holds the ``flags'' for the result of an operation or comparison. Normally, the contents of that -register are either unmodifed by the asm, or the asm is considered to -clobber the contents. +register are either unmodifed by the asm, or the @code{asm} statement is +considered to clobber the contents. On some targets, a special form of output operand exists by which conditions in the flags register may be outputs of the asm. The set of @@ -10630,7 +10634,7 @@ That is, if the current value of @code{*@var{ptr}} is @var{oldval}, then write @var{newval} into @code{*@var{ptr}}. -The ``bool'' version returns true if the comparison is successful and +The ``bool'' version returns @code{true} if the comparison is successful and @var{newval} is written. The ``val'' version returns the contents of @code{*@var{ptr}} before the operation. @@ -10831,18 +10835,18 @@ This compares the contents of @code{*@var{ptr}} with the contents of @code{*@var{expected}}. If equal, the operation is a @emph{read-modify-write} operation that writes @var{desired} into @code{*@var{ptr}}. If they are not equal, the operation is a @emph{read} and the current contents of -@code{*@var{ptr}} are written into @code{*@var{expected}}. @var{weak} is true -for weak compare_exchange, which may fail spuriously, and false for +@code{*@var{ptr}} are written into @code{*@var{expected}}. @var{weak} is @code{true} +for weak compare_exchange, which may fail spuriously, and @code{false} for the strong variation, which never fails spuriously. Many targets only offer the strong variation and ignore the parameter. When in doubt, use the strong variation. -If @var{desired} is written into @code{*@var{ptr}} then true is returned +If @var{desired} is written into @code{*@var{ptr}} then @code{true} is returned and memory is affected according to the memory order specified by @var{success_memorder}. There are no restrictions on what memory order can be used here. -Otherwise, false is returned and memory is affected according +Otherwise, @code{false} is returned and memory is affected according to @var{failure_memorder}. This memory order cannot be @code{__ATOMIC_RELEASE} nor @code{__ATOMIC_ACQ_REL}. It also cannot be a stronger order than that specified by @var{success_memorder}. @@ -10946,7 +10950,7 @@ All memory orders are valid. @deftypefn {Built-in Function} bool __atomic_always_lock_free (size_t size, void *ptr) -This built-in function returns true if objects of @var{size} bytes always +This built-in function returns @code{true} if objects of @var{size} bytes always generate lock-free atomic instructions for the target architecture. @var{size} must resolve to a compile-time constant and the result also resolves to a compile-time constant. @@ -10963,7 +10967,7 @@ if (__atomic_always_lock_free (sizeof (long long), 0)) @deftypefn {Built-in Function} bool __atomic_is_lock_free (size_t size, void *ptr) -This built-in function returns true if objects of @var{size} bytes always +This built-in function returns @code{true} if objects of @var{size} bytes always generate lock-free atomic instructions for the target architecture. If the built-in function is not known to be lock-free, a call is made to a runtime routine named @code{__atomic_is_lock_free}. @@ -10991,7 +10995,7 @@ These built-in functions promote the first two operands into infinite precision type and perform addition on those promoted operands. The result is then cast to the type the third pointer argument points to and stored there. If the stored result is equal to the infinite precision result, the built-in -functions return false, otherwise they return true. As the addition is +functions return @code{false}, otherwise they return @code{true}. As the addition is performed in infinite signed precision, these built-in functions have fully defined behavior for all argument values. @@ -11048,7 +11052,7 @@ than enumerated or boolean type. The built-in functions promote the first two operands into infinite precision signed type and perform addition on those promoted operands. The result is then cast to the type of the third argument. If the cast result is equal to the infinite -precision result, the built-in functions return false, otherwise they return true. +precision result, the built-in functions return @code{false}, otherwise they return @code{true}. The value of the third argument is ignored, just the side effects in the third argument are evaluated, and no integral argument promotions are performed on the last argument. If the third argument is a bit-field, the type used for the result cast has the @@ -12120,7 +12124,7 @@ integer constant expression, is nonzero. Otherwise it returns @var{exp2}. This built-in function is analogous to the @samp{? :} operator in C, except that the expression returned has its type unaltered by promotion rules. Also, the built-in function does not evaluate the expression -that is not chosen. For example, if @var{const_exp} evaluates to true, +that is not chosen. For example, if @var{const_exp} evaluates to @code{true}, @var{exp2} is not evaluated even if it has side effects. This built-in function can return an lvalue if the chosen argument is an @@ -12306,7 +12310,7 @@ if (__builtin_expect (ptr != NULL, 1)) when testing pointer or floating-point values. For the purposes of branch prediction optimizations, the probability that -a @code{__builtin_expect} expression is true is controlled by GCC's +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. @@ -14934,8 +14938,8 @@ Comparison of two paired-single values @code{bc1any2t}/@code{bc1any2f}). These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps} -or @code{cabs.@var{cond}.ps}. The @code{any} forms return true if either -result is true and the @code{all} forms return true if both results are true. +or @code{cabs.@var{cond}.ps}. The @code{any} forms return @code{true} if either +result is @code{true} and the @code{all} forms return @code{true} if both results are @code{true}. For example: @smallexample @@ -14961,8 +14965,8 @@ Comparison of four paired-single values These functions use @code{c.@var{cond}.ps} or @code{cabs.@var{cond}.ps} to compare @var{a} with @var{b} and to compare @var{c} with @var{d}. -The @code{any} forms return true if any of the four results are true -and the @code{all} forms return true if all four results are true. +The @code{any} forms return @code{true} if any of the four results are @code{true} +and the @code{all} forms return @code{true} if all four results are @code{true}. For example: @smallexample @@ -16126,7 +16130,8 @@ add 32. Hence these instructions only modify the FPSCR[32:63] bits by changing the specified bit to a zero or one respectively. The @code{__builtin_set_fpscr_rn} builtin allows changing both of the floating point rounding mode bits. The argument is a 2-bit value. The argument can -either be a const int or stored in a variable. The builtin uses the ISA 3.0 +either be a @code{const int} or stored in a variable. The builtin uses +the ISA 3.0 instruction @code{mffscrn} if available, otherwise it reads the FPSCR, masks the current rounding mode bits out and OR's in the new value. @@ -16182,7 +16187,8 @@ unsigned long long __builtin_unpack_dec128 (_Decimal128, int); The @code{__builtin_set_fpscr_drn} builtin allows changing the three decimal floating point rounding mode bits. The argument is a 3-bit value. The -argument can either be a const int or the value can be stored in a variable. +argument can either be a @code{const int} or the value can be stored in +a variable. The builtin uses the ISA 3.0 instruction @code{mffscdrn} if available. Otherwise the builtin reads the FPSCR, masks the current decimal rounding mode bits out and OR's in the new value. @@ -19573,7 +19579,7 @@ The HTM builtins (with the exception of @code{__builtin_tbegin}) return the full 4-bit condition register value set by their associated hardware instruction. The header file @code{htmintrin.h} defines some macros that can be used to decipher the return value. The @code{__builtin_tbegin} builtin -returns a simple true or false value depending on whether a transaction was +returns a simple @code{true} or @code{false} value depending on whether a transaction was successfully started or not. The arguments of the builtins match exactly the type and order of the associated hardware instruction's operands, except for the @code{__builtin_tcheck} builtin, which does not take any input arguments. @@ -22533,15 +22539,15 @@ This pragma gives the C function @var{oldname} the assembly symbol is defined if this pragma is available (currently on all platforms). @end table -This pragma and the asm labels extension interact in a complicated +This pragma and the @code{asm} labels extension interact in a complicated manner. Here are some corner cases you may want to be aware of: @enumerate @item This pragma silently applies only to declarations with external -linkage. Asm labels do not have this restriction. +linkage. The @code{asm} label feature does not have this restriction. @item In C++, this pragma silently applies only to declarations with -``C'' linkage. Again, asm labels do not have this restriction. +``C'' linkage. Again, @code{asm} labels do not have this restriction. @item If either of the ways of changing the assembly name of a declaration are applied to a declaration whose assembly name has @@ -23924,130 +23930,143 @@ pair of types). @table @code @item __has_nothrow_assign (type) -If @code{type} is const qualified or is a reference type then the trait is -false. Otherwise if @code{__has_trivial_assign (type)} is true then the trait -is true, else if @code{type} is a cv class or union type with copy assignment -operators that are known not to throw an exception then the trait is true, -else it is false. Requires: @code{type} shall be a complete type, -(possibly cv-qualified) @code{void}, or an array of unknown bound. +If @code{type} is @code{const}-qualified or is a reference type then +the trait is @code{false}. Otherwise if @code{__has_trivial_assign (type)} +is @code{true} then the trait is @code{true}, else if @code{type} is +a cv-qualified class or union type with copy assignment operators that are +known not to throw an exception then the trait is @code{true}, else it is +@code{false}. +Requires: @code{type} shall be a complete type, (possibly cv-qualified) +@code{void}, or an array of unknown bound. @item __has_nothrow_copy (type) -If @code{__has_trivial_copy (type)} is true then the trait is true, else if -@code{type} is a cv class or union type with copy constructors that -are known not to throw an exception then the trait is true, else it is false. +If @code{__has_trivial_copy (type)} is @code{true} then the trait is +@code{true}, else if @code{type} is a cv-qualified class or union type +with copy constructors that are known not to throw an exception then +the trait is @code{true}, else it is @code{false}. Requires: @code{type} shall be a complete type, (possibly cv-qualified) @code{void}, or an array of unknown bound. @item __has_nothrow_constructor (type) -If @code{__has_trivial_constructor (type)} is true then the trait is -true, else if @code{type} is a cv class or union type (or array +If @code{__has_trivial_constructor (type)} is @code{true} then the trait +is @code{true}, else if @code{type} is a cv class or union type (or array thereof) with a default constructor that is known not to throw an -exception then the trait is true, else it is false. Requires: -@code{type} shall be a complete type, (possibly cv-qualified) +exception then the trait is @code{true}, else it is @code{false}. +Requires: @code{type} shall be a complete type, (possibly cv-qualified) @code{void}, or an array of unknown bound. @item __has_trivial_assign (type) -If @code{type} is const qualified or is a reference type then the trait is -false. Otherwise if @code{__is_pod (type)} is true then the trait is -true, else if @code{type} is a cv class or union type with a trivial -copy assignment ([class.copy]) then the trait is true, else it is -false. Requires: @code{type} shall be a complete type, (possibly -cv-qualified) @code{void}, or an array of unknown bound. +If @code{type} is @code{const}- qualified or is a reference type then +the trait is @code{false}. Otherwise if @code{__is_pod (type)} is +@code{true} then the trait is @code{true}, else if @code{type} is +a cv-qualified class or union type with a trivial copy assignment +([class.copy]) then the trait is @code{true}, else it is @code{false}. +Requires: @code{type} shall be a complete type, (possibly cv-qualified) +@code{void}, or an array of unknown bound. @item __has_trivial_copy (type) -If @code{__is_pod (type)} is true or @code{type} is a reference type -then the trait is true, else if @code{type} is a cv class or union type -with a trivial copy constructor ([class.copy]) then the trait -is true, else it is false. Requires: @code{type} shall be a complete -type, (possibly cv-qualified) @code{void}, or an array of unknown bound. +If @code{__is_pod (type)} is @code{true} or @code{type} is a reference +type then the trait is @code{true}, else if @code{type} is a cv class +or union type with a trivial copy constructor ([class.copy]) then the trait +is @code{true}, else it is @code{false}. Requires: @code{type} shall be +a complete type, (possibly cv-qualified) @code{void}, or an array of unknown +bound. @item __has_trivial_constructor (type) -If @code{__is_pod (type)} is true then the trait is true, else if -@code{type} is a cv class or union type (or array thereof) with a -trivial default constructor ([class.ctor]) then the trait is true, -else it is false. Requires: @code{type} shall be a complete -type, (possibly cv-qualified) @code{void}, or an array of unknown bound. +If @code{__is_pod (type)} is @code{true} then the trait is @code{true}, +else if @code{type} is a cv-qualified class or union type (or array thereof) +with a trivial default constructor ([class.ctor]) then the trait is @code{true}, +else it is @code{false}. +Requires: @code{type} shall be a complete type, (possibly cv-qualified) +@code{void}, or an array of unknown bound. @item __has_trivial_destructor (type) -If @code{__is_pod (type)} is true or @code{type} is a reference type then -the trait is true, else if @code{type} is a cv class or union type (or -array thereof) with a trivial destructor ([class.dtor]) then the trait -is true, else it is false. Requires: @code{type} shall be a complete -type, (possibly cv-qualified) @code{void}, or an array of unknown bound. +If @code{__is_pod (type)} is @code{true} or @code{type} is a reference type +then the trait is @code{true}, else if @code{type} is a cv class or union +type (or array thereof) with a trivial destructor ([class.dtor]) then +the trait is @code{true}, else it is @code{false}. +Requires: @code{type} shall be a complete type, (possibly cv-qualified) +@code{void}, or an array of unknown bound. @item __has_virtual_destructor (type) If @code{type} is a class type with a virtual destructor -([class.dtor]) then the trait is true, else it is false. Requires: -@code{type} shall be a complete type, (possibly cv-qualified) +([class.dtor]) then the trait is @code{true}, else it is @code{false}. +Requires: @code{type} shall be a complete type, (possibly cv-qualified) @code{void}, or an array of unknown bound. @item __is_abstract (type) If @code{type} is an abstract class ([class.abstract]) then the trait -is true, else it is false. Requires: @code{type} shall be a complete -type, (possibly cv-qualified) @code{void}, or an array of unknown bound. +is @code{true}, else it is @code{false}. +Requires: @code{type} shall be a complete type, (possibly cv-qualified) +@code{void}, or an array of unknown bound. @item __is_base_of (base_type, derived_type) If @code{base_type} is a base class of @code{derived_type} -([class.derived]) then the trait is true, otherwise it is false. -Top-level cv qualifications of @code{base_type} and +([class.derived]) then the trait is @code{true}, otherwise it is @code{false}. +Top-level cv-qualifications of @code{base_type} and @code{derived_type} are ignored. For the purposes of this trait, a -class type is considered is own base. Requires: if @code{__is_class -(base_type)} and @code{__is_class (derived_type)} are true and -@code{base_type} and @code{derived_type} are not the same type -(disregarding cv-qualifiers), @code{derived_type} shall be a complete +class type is considered is own base. +Requires: if @code{__is_class (base_type)} and @code{__is_class (derived_type)} +are @code{true} and @code{base_type} and @code{derived_type} are not the same +type (disregarding cv-qualifiers), @code{derived_type} shall be a complete type. A diagnostic is produced if this requirement is not met. @item __is_class (type) -If @code{type} is a cv class type, and not a union type -([basic.compound]) the trait is true, else it is false. +If @code{type} is a cv-qualified class type, and not a union type +([basic.compound]) the trait is @code{true}, else it is @code{false}. @item __is_empty (type) -If @code{__is_class (type)} is false then the trait is false. +If @code{__is_class (type)} is @code{false} then the trait is @code{false}. Otherwise @code{type} is considered empty if and only if: @code{type} has no non-static data members, or all non-static data members, if any, are bit-fields of length 0, and @code{type} has no virtual members, and @code{type} has no virtual base classes, and @code{type} has no base classes @code{base_type} for which -@code{__is_empty (base_type)} is false. Requires: @code{type} shall -be a complete type, (possibly cv-qualified) @code{void}, or an array -of unknown bound. +@code{__is_empty (base_type)} is @code{false}. +Requires: @code{type} shall be a complete type, (possibly cv-qualified) +@code{void}, or an array of unknown bound. @item __is_enum (type) If @code{type} is a cv enumeration type ([basic.compound]) the trait is -true, else it is false. +@code{true}, else it is @code{false}. @item __is_literal_type (type) If @code{type} is a literal type ([basic.types]) the trait is -true, else it is false. Requires: @code{type} shall be a complete type, -(possibly cv-qualified) @code{void}, or an array of unknown bound. +@code{true}, else it is @code{false}. +Requires: @code{type} shall be a complete type, (possibly cv-qualified) +@code{void}, or an array of unknown bound. @item __is_pod (type) -If @code{type} is a cv POD type ([basic.types]) then the trait is true, -else it is false. Requires: @code{type} shall be a complete type, -(possibly cv-qualified) @code{void}, or an array of unknown bound. +If @code{type} is a cv POD type ([basic.types]) then the trait is @code{true}, +else it is @code{false}. +Requires: @code{type} shall be a complete type, (possibly cv-qualified) +@code{void}, or an array of unknown bound. @item __is_polymorphic (type) If @code{type} is a polymorphic class ([class.virtual]) then the trait -is true, else it is false. Requires: @code{type} shall be a complete -type, (possibly cv-qualified) @code{void}, or an array of unknown bound. +is @code{true}, else it is @code{false}. +Requires: @code{type} shall be a complete type, (possibly cv-qualified) +@code{void}, or an array of unknown bound. @item __is_standard_layout (type) If @code{type} is a standard-layout type ([basic.types]) the trait is -true, else it is false. Requires: @code{type} shall be a complete -type, (possibly cv-qualified) @code{void}, or an array of unknown bound. +@code{true}, else it is @code{false}. +Requires: @code{type} shall be a complete type, (possibly cv-qualified) +@code{void}, or an array of unknown bound. @item __is_trivial (type) If @code{type} is a trivial type ([basic.types]) the trait is -true, else it is false. Requires: @code{type} shall be a complete -type, (possibly cv-qualified) @code{void}, or an array of unknown bound. +@code{true}, else it is @code{false}. +Requires: @code{type} shall be a complete type, (possibly cv-qualified) +@code{void}, or an array of unknown bound. @item __is_union (type) If @code{type} is a cv union type ([basic.compound]) the trait is -true, else it is false. +@code{true}, else it is @code{false}. @item __underlying_type (type) -The underlying type of @code{type}. Requires: @code{type} shall be -an enumeration type ([dcl.enum]). +The underlying type of @code{type}. +Requires: @code{type} shall be an enumeration type ([dcl.enum]). @item __integer_pack (length) When used as the pattern of a pack expansion within a template @@ -24098,7 +24117,7 @@ likely to be removed in the future. @table @code @item __is_same (type1, type2) -A binary type trait: true whenever the type arguments are the same. +A binary type trait: @code{true} whenever the type arguments are the same. @end table -- 2.7.4