Doc: Document -Wpsabi [PR81831]

Per the issue, there were a couple places in the manual where
-Wno-psabi was mentioned, but the option itself was not documented.

gcc/c-family/ChangeLog
	PR c/81831
	* c.opt (Wpsabi): Remove "Undocumented" modifier and add a
	documentation string.

gcc/ChangeLog
	PR c/81831
	* doc/invoke.texi (Option Summary): Add -Wno-psabi.
	(Warning Options): Document -Wpsabi separately from -Wabi.
	Note it's enabled by default, not just implied by -Wabi.
	Replace the detailed example for a GCC 4.4 change for x86
	(which is unlikely to be very interesting nowadays) with
	just a list of all targets that presently diagnose these
	warnings.
	(RS/6000 and PowerPC Options): Add cross-references for
	-Wno-psabi.

2 files changed, 26 insertions, 28 deletions

diff --git a/gcc/c-family/c.opt b/gcc/c-family/c.opt
index ad21698..75b6531 100644
--- a/gcc/c-family/c.opt
+++ b/gcc/c-family/c.opt
@@ -303,7 +303,8 @@ C++ ObjC++ Var(warn_abi_tag) Warning
 Warn if a subobject has an abi_tag attribute that the complete object type does not have.
 
 Wpsabi
-C ObjC C++ ObjC++ LTO Var(warn_psabi) Init(1) Warning Undocumented LangEnabledBy(C ObjC C++ ObjC++,Wabi)
+C ObjC C++ ObjC++ LTO Var(warn_psabi) Init(1) Warning LangEnabledBy(C ObjC C++ ObjC++,Wabi)
+Warn about code affected by incompatible psABI changes.
 
 Wabsolute-value
 C ObjC Var(warn_absolute_value) Warning EnabledBy(Wextra)
diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index 8f51ea6..91ed43d 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -406,7 +406,9 @@ Objective-C and Objective-C++ Dialects}.
 -Wparentheses  -Wno-pedantic-ms-format
 -Wpointer-arith  -Wno-pointer-compare  -Wno-pointer-to-int-cast
 -Wno-pragmas  -Wno-pragma-once-outside-header  -Wno-prio-ctor-dtor
--Wredundant-decls  -Wrestrict  -Wno-return-local-addr  -Wreturn-type
+-Wno-psabi
+-Wredundant-decls  -Wrestrict
+-Wno-return-local-addr  -Wreturn-type
 -Wno-scalar-storage-order  -Wsequence-point
 -Wshadow  -Wshadow=global  -Wshadow=local  -Wshadow=compatible-local
 -Wno-shadow-ivar
@@ -6497,7 +6499,8 @@ of a derived class.
 
 Warn about code affected by ABI changes.  This includes code that may
 not be compatible with the vendor-neutral C++ ABI as well as the psABI
-for the particular target.
+for the particular target.  The latter warnings are also controlled
+separately by @option{-Wpsabi}, which is implied by @option{-Wabi}.
 
 Since G++ now defaults to updating the ABI with each major release,
 normally @option{-Wabi} warns only about C++ ABI compatibility
@@ -6600,27 +6603,21 @@ This was fixed in @option{-fabi-version=10}, the default for GCC 6.1.
 
 @end itemize
 
-This option also enables warnings about psABI-related changes.
-The known psABI changes at this point include:
+@opindex Wpsabi
+@opindex Wno-psabi
+@item -Wpsabi @r{(C, Objective-C, C++ and Objective-C++ only)}
 
-@itemize @bullet
-
-@item
-For SysV/x86-64, unions with @code{long double} members are
-passed in memory as specified in psABI.  Prior to GCC 4.4, this was not
-the case.  For example:
+@option{-Wpsabi} enables warnings about processor-specific ABI
+changes, such as changes in alignment requirements or how function
+arguments are passed.  On several targets, including AArch64, ARM,
+x86, MIPS, RS6000/PowerPC, and S/390, these details have changed
+between different versions of GCC and/or different versions of the C
+or C++ language standards in ways that affect binary compatibility of
+compiled code.  With @option{-Wpsabi}, GCC can detect potentially
+incompatible usages and warn you about them.
 
-@smallexample
-union U @{
-  long double ld;
-  int i;
-@};
-@end smallexample
-
-@noindent
-@code{union U} is now always passed in memory.
-
-@end itemize
+@option{-Wpsabi} is enabled by default, and is also implied by
+@option{-Wabi}.
 
 @opindex Wchanges-meaning
 @opindex Wno-changes-meaning
@@ -32452,18 +32449,18 @@ and for AIX: @samp{vec-extabi}, @samp{vec-default}@.
 Change the current ABI to use IBM extended-precision long double.
 This is not likely to work if your system defaults to using IEEE
 extended-precision long double.  If you change the long double type
-from IEEE extended-precision, the compiler will issue a warning unless
-you use the @option{-Wno-psabi} option.  Requires @option{-mlong-double-128}
-to be enabled.
+from IEEE extended-precision, the compiler issues a warning unless
+you use the @option{-Wno-psabi} option (@pxref{Warning Options}).
+Requires @option{-mlong-double-128} to be enabled.
 
 @opindex mabi=ieeelongdouble
 @item -mabi=ieeelongdouble
 Change the current ABI to use IEEE extended-precision long double.
 This is not likely to work if your system defaults to using IBM
 extended-precision long double.  If you change the long double type
-from IBM extended-precision, the compiler will issue a warning unless
-you use the @option{-Wno-psabi} option.  Requires @option{-mlong-double-128}
-to be enabled.
+from IBM extended-precision, the compiler issues a warning unless
+you use the @option{-Wno-psabi} option (@pxref{Warning Options}).
+Requires @option{-mlong-double-128} to be enabled.
 
 @opindex mabi=elfv1
 @item -mabi=elfv1