[AMDGPU] Update AMD GPU documentation

[t-tye]

Summary

• AMDGPUUsage.rst: Correct AMD GPU DWARF address space table address sizes which are in bits and not bytes.

• clang/.../Options.td: Improve description of AMD GPU options.

• Re-generate ClangComamndLineReference.rst from clang/.../Options.td .

[kzhuravl]

LGTM

clang/docs/ClangCommandLineReference.rst

 .. option:: -fgnuc-version=<arg>
 
 Sets various macros to claim compatibility with the given GCC version (default is 4.2.1)
 
 .. option:: -fgpu-allow-device-init, -fno-gpu-allow-device-init
 
 Allow device side init function in HIP
 
+.. option:: -fgpu-defer-diag, -fno-gpu-defer-diag
+
+Defer host/device related diagnostic messages for CUDA/HIP
+
 .. option:: -fgpu-rdc, -fcuda-rdc, -fno-gpu-rdc
 
 Generate relocatable device code, also known as separate compilation mode
 
 .. option:: -fhip-new-launch-api, -fno-hip-new-launch-api
 
 Use new kernel launching API for HIP
 

 Link stack frames through backchain on System Z
 
 .. option:: -mbranches-within-32B-boundaries
 
 Align selected branches (fused, jcc, jmp) within 32-byte boundary
 
 .. option:: -mcmodel=<arg>, -mcmodel=medany (equivalent to -mcmodel=medium), -mcmodel=medlow (equivalent to -mcmodel=small)
 
+.. option:: -mcode-object-v3, -mno-code-object-v3
+
+Legacy option to specify code object ABI V2 (-mnocode-object-v3) or V3 (-mcode-object-v3) (AMDGPU only)
+
 .. option:: -mconsole<arg>
 
 .. program:: clang1
 .. option:: -mcpu=<arg>, -mv5 (equivalent to -mcpu=hexagonv5), -mv55 (equivalent to -mcpu=hexagonv55), -mv60 (equivalent to -mcpu=hexagonv60), -mv62 (equivalent to -mcpu=hexagonv62), -mv65 (equivalent to -mcpu=hexagonv65), -mv66 (equivalent to -mcpu=hexagonv66), -mv67 (equivalent to -mcpu=hexagonv67), -mv67t (equivalent to -mcpu=hexagonv67t)
 .. program:: clang
 
 .. option:: -mcrc, -mno-crc
 

 .. option:: -mstack-arg-probe, -mno-stack-arg-probe
 
 Enable stack probes
 
 .. option:: -mstack-probe-size=<arg>
 
 Set the stack probe size
 
+.. option:: -mstack-protector-guard-offset=<arg>
+
+Use the given offset for addressing the stack-protector guard
+
+.. option:: -mstack-protector-guard-reg=<arg>
+
+Use the given reg for addressing the stack-protector guard
+
+.. option:: -mstack-protector-guard=<arg>
+
+Use the given guard (global, tls) for addressing the stack-protector guard
+
 .. option:: -mstackrealign, -mno-stackrealign
 
 Force realign the stack at entry to every function
 
 .. option:: -msvr4-struct-return
 
 Return small structs in registers (PPC32 only)
 

 .. option:: -mtls-size=<arg>
 
 Specify bit size of immediate TLS offsets (AArch64 ELF only): 12 (for 4KB) \| 24 (for 16MB, default) \| 32 (for 4GB) \| 48 (for 256TB, needs -mcmodel=large)
 
 .. program:: clang1
 .. option:: -mtune=<arg>
 .. program:: clang
 
-Only supported on X86. Otherwise accepted for compatibility with GCC.
+Only supported on X86 and RISC-V. Otherwise accepted for compatibility with GCC.
 
 .. option:: -mtvos-version-min=<arg>, -mappletvos-version-min=<arg>
 
 .. option:: -municode<arg>
 
 .. option:: -mvx, -mno-vx
 
 .. option:: -mwarn-nonportable-cfstrings, -mno-warn-nonportable-cfstrings
 
 .. option:: -mwatchos-version-min=<arg>
 
 .. option:: -mwavefrontsize64, -mno-wavefrontsize64
 
-Wavefront size 64 is used
+Specify wavefront size 64 mode (AMDGPU only)
 
 .. option:: -mwindows<arg>
 
 .. option:: -mx32
 
 AARCH64
 -------
 .. option:: -fcall-saved-x10

 Add .note.gnu.property with BTI to assembly files (AArch64 only)
 
 .. option:: -msve-vector-bits=<arg>
 
 Specify the size in bits of an SVE vector register. Defaults to the vector length agnostic value of "scalable". (AArch64 only)
 
 AMDGPU
 ------
-.. option:: -mcode-object-v3, -mno-code-object-v3
-
-Legacy option to specify code object v3 (AMDGPU only)
-
 .. option:: -mcumode, -mno-cumode
 
-CU wavefront execution mode is used (AMDGPU only)
+Specify CU (-mcumode) or WGP (-mno-cumode) wavefront execution mode (AMDGPU only)
 
 .. option:: -msram-ecc, -mno-sram-ecc
 
-Enable SRAM ECC (AMDGPU only)
+Specify SRAM ECC mode (AMDGPU only)
 
 .. option:: -mxnack, -mno-xnack
 
-Enable XNACK (AMDGPU only)
+Specify XNACK mode (AMDGPU only)
 
 ARM
 ---
-.. option:: -fAAPCSBitfieldLoad
+.. option:: -faapcs-bitfield-load
 
 Follows the AAPCS standard that all volatile bit-field write generates at least one load. (ARM only).
 
+.. option:: -faapcs-bitfield-width, -fno-aapcs-bitfield-width
+
+Follow the AAPCS standard requirement stating that volatile bit-field width is dictated by the field container type. (ARM only).
+
 .. option:: -ffixed-r9
 
 Reserve the r9 register (ARM only)
 
 .. option:: -mcmse
 
 Allow use of CMSE (Armv8-M Security Extensions)
 

 .. program:: clang1
 .. option:: -gsplit-dwarf=<arg>
 .. program:: clang
 
 Set DWARF fission mode to either 'split' or 'single'
 
 .. option:: -gstrict-dwarf, -gno-strict-dwarf
 
-.. option:: -gz
-
-DWARF debug sections compression type
-
-.. program:: clang1
-.. option:: -gz=<arg>
-.. program:: clang
+.. option:: -gz=<arg>, -gz (equivalent to -gz=zlib)
 
 DWARF debug sections compression type
 
 Static analyzer flags
 =====================
 
 Flags controlling the behavior of the Clang Static Analyzer.
 

clang/include/clang/Driver/Options.td

 def mno_tail_call : Flag<["-"], "mno-tail-call">, Group<m_wasm_Features_Group>;
 def mreference_types : Flag<["-"], "mreference-types">, Group<m_wasm_Features_Group>;
 def mno_reference_types : Flag<["-"], "mno-reference-types">, Group<m_wasm_Features_Group>;
 def mexec_model_EQ : Joined<["-"], "mexec-model=">, Group<m_wasm_Features_Driver_Group>,
                      Values<"command,reactor">,
                      HelpText<"Execution model (WebAssembly only)">;
 
 def mcode_object_v3_legacy : Flag<["-"], "mcode-object-v3">, Group<m_Group>,
-  HelpText<"Legacy option to specify code object v3 (AMDGPU only)">;
-def mno_code_object_v3_legacy : Flag<["-"], "mno-code-object-v3">, Group<m_Group>,
-  HelpText<"Legacy option to specify code object v2 (AMDGPU only)">;
+  HelpText<"Legacy option to specify code object ABI V2 (-mnocode-object-v3) or V3 (-mcode-object-v3) (AMDGPU only)">;
+def mno_code_object_v3_legacy : Flag<["-"], "mno-code-object-v3">, Group<m_Group>;
+
+def mcumode : Flag<["-"], "mcumode">, Group<m_amdgpu_Features_Group>,
+  HelpText<"Specify CU (-mcumode) or WGP (-mno-cumode) wavefront execution mode (AMDGPU only)">;
+def mno_cumode : Flag<["-"], "mno-cumode">, Group<m_amdgpu_Features_Group>;
 
-def mxnack : Flag<["-"], "mxnack">, Group<m_amdgpu_Features_Group>,
-  HelpText<"Enable XNACK (AMDGPU only)">;
-def mno_xnack : Flag<["-"], "mno-xnack">, Group<m_amdgpu_Features_Group>,
-  HelpText<"Disable XNACK (AMDGPU only)">;
 def msram_ecc : Flag<["-"], "msram-ecc">, Group<m_amdgpu_Features_Group>,
-  HelpText<"Enable SRAM ECC (AMDGPU only)">;
-def mno_sram_ecc : Flag<["-"], "mno-sram-ecc">, Group<m_amdgpu_Features_Group>,
-  HelpText<"Disable SRAM ECC (AMDGPU only)">;
+  HelpText<"Specify SRAM ECC mode (AMDGPU only)">;
+def mno_sram_ecc : Flag<["-"], "mno-sram-ecc">, Group<m_amdgpu_Features_Group>;
 
-def mcumode : Flag<["-"], "mcumode">, Group<m_amdgpu_Features_Group>,
-  HelpText<"CU wavefront execution mode is used (AMDGPU only)">;
-def mno_cumode : Flag<["-"], "mno-cumode">, Group<m_amdgpu_Features_Group>,
-  HelpText<"WGP wavefront execution mode is used (AMDGPU only)">;
-
-def mwavefrontsize64 : Flag<["-"], "mwavefrontsize64">,
-  Group<m_Group>, HelpText<"Wavefront size 64 is used">;
-def mno_wavefrontsize64 : Flag<["-"], "mno-wavefrontsize64">,
-  Group<m_Group>, HelpText<"Wavefront size 32 is used">;
+def mwavefrontsize64 : Flag<["-"], "mwavefrontsize64">, Group<m_Group>,
+  HelpText<"Specify wavefront size 64 mode (AMDGPU only)">;
+def mno_wavefrontsize64 : Flag<["-"], "mno-wavefrontsize64">, Group<m_Group>,
+  HelpText<"Specify wavefront size 32 mode (AMDGPU only)">;
+
+def mxnack : Flag<["-"], "mxnack">, Group<m_amdgpu_Features_Group>,
+  HelpText<"Specify XNACK mode (AMDGPU only)">;
+def mno_xnack : Flag<["-"], "mno-xnack">, Group<m_amdgpu_Features_Group>;
 
 def faltivec : Flag<["-"], "faltivec">, Group<f_Group>, Flags<[DriverOption]>;
 def fno_altivec : Flag<["-"], "fno-altivec">, Group<f_Group>, Flags<[DriverOption]>;
 def maltivec : Flag<["-"], "maltivec">, Group<m_ppc_Features_Group>;
 def mno_altivec : Flag<["-"], "mno-altivec">, Group<m_ppc_Features_Group>;
 def mpcrel: Flag<["-"], "mpcrel">, Group<m_ppc_Features_Group>;
 def mno_pcrel: Flag<["-"], "mno-pcrel">, Group<m_ppc_Features_Group>;
 def mspe : Flag<["-"], "mspe">, Group<m_ppc_Features_Group>;

llvm/docs/AMDGPUUsage.rst

.. table:: AMDGPU DWARF Address Space Mapping
    --------------------------------------- ----- ---------------- ----------------- -----------------------
    Address Space Name                      Value Address Bit Size Address Space
    --------------------------------------- ----- ------- -------- ----------------- -----------------------
    ..                                            64-bit  32-bit
                                                  process process
                                                  address address
                                                  space   space
    ======================================= ===== ======= ======== ================= =======================
-   ``DW_ASPACE_none``                      0x00  8       4        Global            *default address space*
-   ``DW_ASPACE_AMDGPU_generic``            0x01  8       4        Generic (Flat)
-   ``DW_ASPACE_AMDGPU_region``             0x02  4       4        Region (GDS)
-   ``DW_ASPACE_AMDGPU_local``              0x03  4       4        Local (group/LDS)
+   ``DW_ASPACE_none``                      0x00  64      32       Global            *default address space*
+   ``DW_ASPACE_AMDGPU_generic``            0x01  64      32       Generic (Flat)
+   ``DW_ASPACE_AMDGPU_region``             0x02  32      32       Region (GDS)
+   ``DW_ASPACE_AMDGPU_local``              0x03  32      32       Local (group/LDS)
    *Reserved*                              0x04
-   ``DW_ASPACE_AMDGPU_private_lane``       0x05  4       4        Private (Scratch) *focused lane*
-   ``DW_ASPACE_AMDGPU_private_wave``       0x06  4       4        Private (Scratch) *unswizzled wavefront*
+   ``DW_ASPACE_AMDGPU_private_lane``       0x05  32      32       Private (Scratch) *focused lane*
+   ``DW_ASPACE_AMDGPU_private_wave``       0x06  32      32       Private (Scratch) *unswizzled wavefront*
    ======================================= ===== ======= ======== ================= =======================
 
 See :ref:`amdgpu-address-spaces` for information on the AMDGPU address spaces
 including address size and NULL value.
 
 The ``DW_ASPACE_none`` address space is the default target architecture address
 space used in DWARF operations that do not specify an address space. It
 therefore has to map to the global address space so that the ``DW_OP_addr*`` and