add comments

python · picnixz · Oct 5, 2024 · Oct 5, 2024 · Oct 5, 2024 · Oct 6, 2024
commit bd3589feb1adb6f0e8bd0387c784e8e3bcc99cf7
diff --git a/Include/internal/pycore_cpuinfo_cpuid_features.h b/Include/internal/pycore_cpuinfo_cpuid_features.h
@@ -42,14 +42,14 @@ import os
 import sys
 
 ROOT = os.getcwd()
-TOOL = os.path.join(ROOT, 'Tools/cpuinfo/cpuid_features_gen.py')
+TOOL = os.path.join(ROOT, "Tools/cpuinfo/cpuid_features_gen.py")
 TOOL = os.path.realpath(TOOL)
 
 if not os.path.exists(TOOL):
     raise FileNotFoundError(TOOL)
 
 sys.path.insert(0, os.path.dirname(os.path.dirname(TOOL)))
-module = importlib.import_module('cpuinfo.cpuid_features_gen')
+module = importlib.import_module("cpuinfo.cpuid_features_gen")
 print(module.generate_cpuid_features_enum("py_cpuid_feature_mask"))
 [python start generated code]*/
 typedef enum py_cpuid_feature_mask {
@@ -96,7 +96,7 @@ typedef enum py_cpuid_feature_mask {
     Py_CPUID_MASK_EDX_L7S1_AVX_NE_CONVERT       = 0x00000020,    // bit = 5
     Py_CPUID_MASK_EDX_L7S1_AVX_VNNI_INT16       = 0x00000400,    // bit = 10
 } py_cpuid_feature_mask;
-/*[python end generated code: output=c4460242e465fa91 input=a07f431329efd11e]*/
+/*[python end generated code: output=c4460242e465fa91 input=61d2b5f1bc368b94]*/
 // fmt: on
 
 #endif // !Py_INTERNAL_CPUINFO_CPUID_FEATURES_H
diff --git a/Include/internal/pycore_cpuinfo_xsave_features.h b/Include/internal/pycore_cpuinfo_xsave_features.h
@@ -2,7 +2,9 @@
  * @author Bénédikt Tran
  * @seealso Tools/cpuinfo/xsave_features_gen.py
  *
- * XSAVE state components (XCR0 control register)
+ * XSAVE state components (XCR0 control register).
+ *
+ * See https://en.wikipedia.org/wiki/Control_register#XCR0_and_XSS.
  */
 #ifndef Py_INTERNAL_CPUINFO_XSAVE_FEATURES_H
 #define Py_INTERNAL_CPUINFO_XSAVE_FEATURES_H
@@ -24,14 +26,14 @@ import os
 import sys
 
 ROOT = os.getcwd()
-TOOL = os.path.join(ROOT, 'Tools/cpuinfo/xsave_features_gen.py')
+TOOL = os.path.join(ROOT, "Tools/cpuinfo/xsave_features_gen.py")
 TOOL = os.path.realpath(TOOL)
 
 if not os.path.exists(TOOL):
     raise FileNotFoundError(TOOL)
 
 sys.path.insert(0, os.path.dirname(os.path.dirname(TOOL)))
-module = importlib.import_module('cpuinfo.xsave_features_gen')
+module = importlib.import_module("cpuinfo.xsave_features_gen")
 print(module.generate_xsave_features_enum("py_xsave_feature_mask"))
 [python start generated code]*/
 typedef enum py_xsave_feature_mask {
@@ -41,7 +43,7 @@ typedef enum py_xsave_feature_mask {
     Py_XSAVE_MASK_XCR0_AVX512_ZMM_HI256 = 0x00000040,    // bit = 6
     Py_XSAVE_MASK_XCR0_AVX512_HI16_ZMM  = 0x00000080,    // bit = 7
 } py_xsave_feature_mask;
-/*[python end generated code: output=9a476ed0abbc617b input=78e3d4ff6b796edb]*/
+/*[python end generated code: output=9a476ed0abbc617b input=41f35058299c0118]*/
 // fmt: on
 
 #endif // !Py_INTERNAL_CPUINFO_XSAVE_FEATURES_H
diff --git a/Tools/cpuinfo/cpuid_features_gen.py b/Tools/cpuinfo/cpuid_features_gen.py
@@ -17,6 +17,8 @@
 
 The LEAF value should only 1 or 7 as other values may have different
 meanings depending on the underlying architecture.
+
+.. seealso:: Include/internal/pycore_cpuinfo_cpuid_features.h
 """
 
 from __future__ import annotations
@@ -39,7 +41,8 @@
     type Feature = str
     type Bit = int
 
-CPUID_FEATURES: Final[dict[CPUIDFeatureFamily, dict[Feature, Bit]]] = {
+CPUID_FEATURES: Final[dict[FeatureFamily, dict[Feature, Bit]]] = {
+    # See https://en.wikipedia.org/wiki/CPUID#EAX=1:_Processor_Info_and_Feature_Bits.
     (1, 0, "ECX"): {
         "SSE3": 0,
         "PCLMULQDQ": 1,
@@ -57,6 +60,7 @@
         "SSE": 25,
         "SSE2": 26,
     },
+    # See https://en.wikipedia.org/wiki/CPUID#EAX=7,_ECX=0:_Extended_Features.
     (7, 0, "EBX"): {
         "AVX2": 5,
         "AVX512_F": 16,
@@ -80,6 +84,7 @@
         "AVX512_4FMAPS": 3,
         "AVX512_VP2INTERSECT": 8,
     },
+    # See https://en.wikipedia.org/wiki/CPUID#EAX=7,_ECX=1:_Extended_Features.
     (7, 1, "EAX"): {
         "AVX_VNNI": 4,
         "AVX_IFMA": 23,
@@ -109,6 +114,11 @@ def get_member_name(
 
 
 def generate_cpuid_features_enum(enum_name: str) -> str:
+    """Used by Include/internal/pycore_cpuinfo_cpuid_features.h.
+
+    The C enumeration is generated by this function and Argument Clinic.
+    """
+
     # The enumeration is rendered as follows:
     #
     #   <INDENT><MEMBER_NAME> <TAB>= 0x<MASK>, <TAB>// bit = BIT

diff --git a/Tools/cpuinfo/xsave_features_gen.py b/Tools/cpuinfo/xsave_features_gen.py
@@ -1,5 +1,9 @@
 """
 Generate enumeration for XSAVE state components (XCR0 control register).
+
+See https://en.wikipedia.org/wiki/Control_register#XCR0_and_XSS.
+
+.. seealso:: Include/internal/pycore_cpuinfo_xsave_features.h
 """
 
 from __future__ import annotations
@@ -36,6 +40,11 @@ def get_member_name(feature: Feature) -> str:
 
 
 def generate_xsave_features_enum(enum_name: str) -> str:
+    """Used by Include/internal/pycore_cpuinfo_xsave_features.h.
+
+    The C enumeration is generated by this function and Argument Clinic.
+    """
+
     # The enumeration is rendered as follows:
     #
     #   <INDENT><MEMBER_NAME> <TAB>= 0x<MASK>, <TAB>// bit = BIT