Documented '-m' flags for machine specific instruction extensions.

See #18641 'Documenting the Expected Undocumented Flags'

2 files changed, 142 insertions, 11 deletions

diff --git a/docs/users_guide/expected-undocumented-flags.txt b/docs/users_guide/expected-undocumented-flags.txt
index 1a0c75413c..1b5b805616 100644
--- a/docs/users_guide/expected-undocumented-flags.txt
+++ b/docs/users_guide/expected-undocumented-flags.txt
@@ -108,16 +108,6 @@
 -instantiated-with
 -keep-hi-file
 -keep-o-file
--mavx
--mavx2
--mavx512cd
--mavx512er
--mavx512f
--mavx512pf
--mbmi
--msse
--msse3
--msse4
 -n
 -no-auto
 -no-auto-all
diff --git a/docs/users_guide/using.rst b/docs/users_guide/using.rst
index 51228aac7b..728d1cdb79 100644
--- a/docs/users_guide/using.rst
+++ b/docs/users_guide/using.rst
@@ -1284,6 +1284,103 @@ Platform-specific Flags
 
 Some flags only make sense for particular target platforms.
 
+.. ghc-flag:: -mavx
+    :shortdesc: (x86 only) Enable support for AVX SIMD extensions
+    :type: dynamic
+    :category: platform-options
+
+    (x86 only) These SIMD instructions are currently not supported by
+    the :ref:`native code generator <native-code-gen>`. Enabling this flag
+    has no effect and is only present for future extensions.
+
+    The :ref:`LLVM backend <llvm-code-gen>` may use AVX if your
+    processor supports it, but detects this automatically, so no flag is
+    required.
+
+.. ghc-flag:: -mavx2
+    :shortdesc: (x86 only) Enable support for AVX2 SIMD extensions
+    :type: dynamic
+    :category: platform-options
+
+    (x86 only) These SIMD instructions are currently not supported by
+    the :ref:`native code generator <native-code-gen>`. Enabling this flag
+    has no effect and is only present for future extensions.
+
+    The :ref:`LLVM backend <llvm-code-gen>` may use AVX2 if your
+    processor supports it, but detects this automatically, so no flag is
+    required.
+
+.. ghc-flag:: -mavx512cd
+    :shortdesc: (x86 only) Enable support for AVX512-CD SIMD extensions
+    :type: dynamic
+    :category: platform-options
+
+    (x86 only) These SIMD instructions are currently not supported by
+    the :ref:`native code generator <native-code-gen>`. Enabling this flag
+    has no effect and is only present for future extensions.
+
+    The :ref:`LLVM backend <llvm-code-gen>` may use AVX512 if your
+    processor supports it, but detects this automatically, so no flag is
+    required.
+
+.. ghc-flag:: -mavx512er
+    :shortdesc: (x86 only) Enable support for AVX512-ER SIMD extensions
+    :type: dynamic
+    :category: platform-options
+
+    (x86 only) These SIMD instructions are currently not supported by
+    the :ref:`native code generator <native-code-gen>`. Enabling this flag
+    has no effect and is only present for future extensions.
+
+    The :ref:`LLVM backend <llvm-code-gen>` may use AVX512 if your
+    processor supports it, but detects this automatically, so no flag is
+    required.
+
+.. ghc-flag:: -mavx512f
+    :shortdesc: (x86 only) Enable support for AVX512-F SIMD extensions
+    :type: dynamic
+    :category: platform-options
+
+    (x86 only) These SIMD instructions are currently not supported by
+    the :ref:`native code generator <native-code-gen>`. Enabling this flag
+    has no effect and is only present for future extensions.
+
+    The :ref:`LLVM backend <llvm-code-gen>` may use AVX512 if your
+    processor supports it, but detects this automatically, so no flag is
+    required.
+
+.. ghc-flag:: -mavx512pf
+    :shortdesc: (x86 only) Enable support for AVX512-PF SIMD extensions
+    :type: dynamic
+    :category: platform-options
+
+    (x86 only) These SIMD instructions are currently not supported by
+    the :ref:`native code generator <native-code-gen>`. Enabling this flag
+    has no effect and is only present for future extensions.
+
+    The :ref:`LLVM backend <llvm-code-gen>` may use AVX512 if your
+    processor supports it, but detects this automatically, so no flag is
+    required.
+
+.. ghc-flag:: -msse
+    :shortdesc: (x86 only) Use SSE for floating-point operations
+    :type: dynamic
+    :category: platform-options
+
+    (x86 only) Use the SSE registers and
+    instruction set to implement floating point operations when using
+    the :ref:`native code generator <native-code-gen>`. This gives a
+    substantial performance improvement for floating point, but the
+    resulting compiled code will only run on processors that support
+    SSE (Intel Pentium 3 and later, or AMD Athlon XP and later). The
+    :ref:`LLVM backend <llvm-code-gen>` will also use SSE if your
+    processor supports it but detects this automatically so no flag is
+    required.
+
+    Since GHC 8.10, SSE2 is assumed to be present on both
+    x86 and x86-64 platforms and will be used by default.
+    Even when setting this flag, SSE2 will be used instead.
+
 .. ghc-flag:: -msse2
     :shortdesc: (x86 only) Use SSE2 for floating-point operations
     :type: dynamic
@@ -1299,7 +1396,40 @@ Some flags only make sense for particular target platforms.
     processor supports it but detects this automatically so no flag is
     required.
 
-    SSE2 is unconditionally used on x86-64 platforms.
+    Since GHC 8.10, SSE2 is assumed to be present on both
+    x86 and x86-64 platforms and will be used by default.
+
+.. ghc-flag:: -msse3
+    :shortdesc: (x86 only) Use SSE3 for floating-point operations
+    :type: dynamic
+    :category: platform-options
+
+    (x86 only) Use the SSE3 instruction set to
+    implement some floating point and bit operations when using the
+    :ref:`native code generator <native-code-gen>`.
+
+    Note that the current version does not use SSE3 specific instructions
+    and only requires SSE2 processor support.
+
+    The :ref:`LLVM backend <llvm-code-gen>` will also use
+    SSE3 if your processor supports it but detects this automatically
+    so no flag is required.
+
+.. ghc-flag:: -msse4
+    :shortdesc: (x86 only) Use SSE4 for floating-point operations
+    :type: dynamic
+    :category: platform-options
+
+    (x86 only) Use the SSE4 instruction set to
+    implement some floating point and bit operations when using the
+    :ref:`native code generator <native-code-gen>`.
+
+    Note that the current version does not use SSE4 specific instructions
+    and only requires SSE2 processor support.
+
+    The :ref:`LLVM backend <llvm-code-gen>` will also use
+    SSE4 if your processor supports it but detects this automatically
+    so no flag is required.
 
 .. ghc-flag:: -msse4.2
     :shortdesc: (x86 only) Use SSE4.2 for floating-point operations
@@ -1314,6 +1444,17 @@ Some flags only make sense for particular target platforms.
     SSE4.2 if your processor supports it but detects this automatically
     so no flag is required.
 
+.. ghc-flag:: -mbmi
+    :shortdesc: (x86 only) Use BMI1 for bit manipulation operations
+    :type: dynamic
+    :category: platform-options
+
+    (x86 only) Use the BMI1 instruction set to implement some bit operations
+    when using the :ref:`native code generator <native-code-gen>`.
+
+    Note that the current version does not use BMI specific instructions,
+    so using this flag has no effect.
+
 .. ghc-flag:: -mbmi2
     :shortdesc: (x86 only) Use BMI2 for bit manipulation operations
     :type: dynamic