[PATCH v3 0/2] x86: AMX enabling example with new constants

[PATCH v3 0/2] x86: AMX enabling example with new constants

[Chang S. Bae]

Hi all,

Here are the changes from the last version [1]:
* Add AMX feature numbers as ABI constants (Tony Luck).
* Revise sentences in the documentation (Bagas Sanjaya).
* Adjust the code example.

Thank you Tony and Bagas for the feedback.

=== Cover Letter ===

With the AMX support in the mainline, recently I heard some folks had a
hard time understanding the AMX enabling process. A code example is
expected to clarify the steps. Along with that, add a couple of ABI
constants useful for the feature enabling.

The arch_prctl(2) manual page [2] is missing these new options. Perhaps,
the man-page update follows up along with this.

These changes can be found in the repo:
  git://github.com/intel/amx-linux.git doc

And the compiled preview is available here:
  https://htmlpreview.github.io/?https://github.com/intel/amx-linux/doc-web/x86/xstate.html

Thanks,
Chang

[1] https://lore.kernel.org/lkml/20220629224235.20589-1-chang.seok.bae@intel.com/
[2] arch_prctl(2): https://man7.org/linux/man-pages/man2/arch_prctl.2.html

Chang S. Bae (2):
  x86/arch_prctl: Add AMX feature numbers as ABI constants
  Documentation/x86: Add the AMX enabling example

 Documentation/x86/xstate.rst      | 55 +++++++++++++++++++++++++++++++
 arch/x86/include/uapi/asm/prctl.h |  3 ++
 2 files changed, 58 insertions(+)


base-commit: 32346491ddf24599decca06190ebca03ff9de7f8
-- 
2.17.1

[PATCH v3 1/2] x86/arch_prctl: Add AMX feature numbers as ABI constants

[Chang S. Bae]

AMX state is dynamically enabled by the architecture-specific prctl().
Expose the XSTATE numbers as ABI constants. It will help applications as no
more spec look-up is needed for these numbers.

Signed-off-by: Chang S. Bae <chang.seok.bae@intel.com>
Cc: Tony Luck <tony.luck@intel.com>
Cc: linux-kernel@vger.kernel.org
---
Changes from v2:
* Add as a new patch (Tony Luck).
---
 arch/x86/include/uapi/asm/prctl.h | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/arch/x86/include/uapi/asm/prctl.h b/arch/x86/include/uapi/asm/prctl.h
index 500b96e71f18..f298c778f856 100644
--- a/arch/x86/include/uapi/asm/prctl.h
+++ b/arch/x86/include/uapi/asm/prctl.h
@@ -16,6 +16,9 @@
 #define ARCH_GET_XCOMP_GUEST_PERM	0x1024
 #define ARCH_REQ_XCOMP_GUEST_PERM	0x1025
 
+#define ARCH_XCOMP_TILECFG		17
+#define ARCH_XCOMP_TILEDATA		18
+
 #define ARCH_MAP_VDSO_X32		0x2001
 #define ARCH_MAP_VDSO_32		0x2002
 #define ARCH_MAP_VDSO_64		0x2003
-- 
2.17.1

[PATCH v3 2/2] Documentation/x86: Add the AMX enabling example

[Chang S. Bae]

Explain steps to enable the dynamic feature with a code example.

Signed-off-by: Chang S. Bae <chang.seok.bae@intel.com>
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
Cc: Dave Hansen <dave.hansen@intel.com>
Cc: Bagas Sanjaya <bagasdotme@gmail.com>
Cc: linux-doc@vger.kernel.org
Cc: linux-kernel@vger.kernel.org
---
Changes from v1:
* Update the description without mentioning CPUID & XGETBV (Dave Hansen).

Changes from v2:
* Massage sentences (Bagas Sanjaya).
* Adjust the example with the (future) prctl.h.
---
 Documentation/x86/xstate.rst | 55 ++++++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)

diff --git a/Documentation/x86/xstate.rst b/Documentation/x86/xstate.rst
index 5cec7fb558d6..dbe7ca854d2a 100644
--- a/Documentation/x86/xstate.rst
+++ b/Documentation/x86/xstate.rst
@@ -64,6 +64,61 @@ the handler allocates a larger xstate buffer for the task so the large
 state can be context switched. In the unlikely cases that the allocation
 fails, the kernel sends SIGSEGV.
 
+AMX TILE_DATA enabling example
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Below is the example of how userspace applications enable
+TILE_DATA dynamically:
+
+  1. The application first needs to query the kernel for AMX
+     support::
+
+        #include <asm/prctl.h>
+        #include <sys/syscall.h>
+        #include <stdio.h>
+        #include <unistd.h>
+
+        #ifndef ARCH_GET_XCOMP_SUPP
+        #define ARCH_GET_XCOMP_SUPP  0x1021
+        #endif
+
+        #ifndef ARCH_XCOMP_TILECFG
+        #define ARCH_XCOMP_TILECFG   17
+        #endif
+
+        #ifndef ARCH_XCOMP_TILEDATA
+        #define ARCH_XCOMP_TILEDATA  18
+        #endif
+
+        #define MASK_XCOMP_TILE      ((1 << ARCH_XCOMP_TILECFG) | \
+                                      (1 << ARCH_XCOMP_TILEDATA))
+
+        unsigned long features;
+        long rc;
+
+        ...
+
+        rc = syscall(SYS_arch_prctl, ARCH_GET_XCOMP_SUPP, &features);
+
+        if (!rc && (features & MASK_XCOMP_TILE) == MASK_XCOMP_TILE)
+            printf("AMX is available.\n");
+
+  2. After that, determining support for AMX, an application must
+     explicitly ask permission to use it::
+
+        #ifndef ARCH_REQ_XCOMP_PERM
+        #define ARCH_REQ_XCOMP_PERM  0x1023
+        #endif
+
+        ...
+
+        rc = syscall(SYS_arch_prctl, ARCH_REQ_XCOMP_PERM, ARCH_XCOMP_TILEDATA);
+
+        if (!rc)
+            printf("AMX is ready for use.\n");
+
+Note this example does not include the sigaltstack preparation.
+
 Dynamic features in signal frames
 ---------------------------------
 
-- 
2.17.1

RE: [PATCH v3 0/2] x86: AMX enabling example with new constants

[Luck, Tony]

> The arch_prctl(2) manual page [2] is missing these new options. Perhaps,
> the man-page update follows up along with this.

This isn't the right process to get a manual page updated.

See:

https://www.kernel.org/doc/man-pages/contributing.html

then log a bug, write a patch, and submit it to add the AMX options.

-Tony

Re: [PATCH v3 0/2] x86: AMX enabling example with new constants

[Chang S. Bae]

On 7/21/2022 1:53 PM, Luck, Tony wrote:
>> The arch_prctl(2) manual page [2] is missing these new options. Perhaps,
>> the man-page update follows up along with this.
> 
> This isn't the right process to get a manual page updated.
> 
> See:
> 
> https://www.kernel.org/doc/man-pages/contributing.html
> 
> then log a bug, write a patch, and submit it to add the AMX options.

Indeed. I didn't intend this series to initiate the process to update 
the man page. Instead, I wanted to establish the kernel doc before 
starting it. But it looks like not super clear, sorry.

Thanks,
Chang