gcc/ChangeLog:
* doc/extend.texi: Consistemtly use @code for const and volatile
qualifiers and asm statements.
===================================================================
@@ -8483,7 +8483,8 @@ All basic @code{asm} blocks are implicitly volatil
@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{
@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,11 +8799,11 @@ GCC's optimizers do not treat this code like the n
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));
@@ -8808,9 +8810,10 @@ 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 sta
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 add
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}} wi
@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),
@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 ope
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. Otherwis
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
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 (_Decim
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{__bu
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
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