Add AMX and other Apple proprietary instructions.

AddExtensions.md

@@ -0,0 +1,70 @@
+# Adding new extensions
+
+Some architectures have processor extensions not defined in upstream LLVM.
+If we want to have them in Capstone, we can write the `.td` files for them here.
+
+The process is rather straight forward.
+
+1. Write all definitions into a new `llvm/lib/Target/<ARCH>/<ARCH>NewExtension.td` file.
+2. Define a feature and property for the new extension:
+    ```python
+    def FeatureExtensionName : SubtargetFeature<"extenion_name", "HasExtensionName", "true",
+      "Enable the new extension bla bla bla.">;
+
+    def HasExtensionName : Predicate<"Subtarget->hasExtensionName()">,
+                           AssemblerPredicate<(all_of FeatureExtensionName), "extenion_name">;  
+    ```
+3. Ensure the newly defined instructions have `let Predicates = [HasExtensionName];` set.
+4. Add or exclude the extension from existing processor models:
+    - Search for `list<Predicate> UnsupportedFeatures` in the target directory.
+      Add `HasExtensionName` to all processor models which don't support it.
+    - The processor models which do support it, need the instructions in the scheduler.
+      Check how it is done in the processor's scheduler file.
+5. Include the `<ARCH>NewExtension.td` at the bottom of `<ARCH>InstrInfo.td` with `include "<ARCH>NewExtension.td"`.
+
+**Note:** As an example you can refer to `AArch64AppleProprietary.td`.
+Also search for `HasAMX` and `FeatureAMX` to see how those flags are used in the files.
+
+# Deprecated Features
+
+Capstone needs to support features which were removed by LLVM in the past.
+Here we explain how to reintroduce them.
+
+## Reintroduction
+
+To get the old features back we copy them from the old `.td` files and include them in the new ones.
+
+To include removed features from previous LLVM versions do the following:
+
+1. Checkout the last LLVM version the feature was present.
+2. Copy all feature related definitions into a `<ARCH>Deprecated.td` file.
+3. Checkout the newest LLVM version again.
+4. Wrap the different definition types in include guards. For example the `InstrInfo` definitions could be included in:
+
+    ```
+    #ifndef INCLUDED_CAPSTONE_DEPR_INSTR
+    #ifdef CAPSTONE_DEPR_INSTR
+    #define INCLUDED_CAPSTONE_DEPR_INSTR // Ensures it is only included once
+
+    [Instruction definitions of removed feature]
+
+    #endif // INCLUDED_CAPSTONE_DEPR_INSTR
+    #endif // CAPSTONE_DEPR_INSTR
+    ```
+
+    _Note that the order of `#ifndef` and `#ifdef` matters (otherwise you'll get an error from `tblgen`)._
+
+    **This step is somewhat optional. It might be enough to write all definitions in a single file and `#include` them once into `ARCHInstrInfo.td` at the bottom.**
+
+5. Include the definitions in the current definition files with:
+
+    ```
+    #define CAPSTONE_DEPR_INSTR
+    include "<ARCH>Deprecated.td"
+    ```
+
+## Notes
+- It is possible that you have to change some definitions slightly.
+Because certain classes no longer exist or were replaced (e.g.: `GCCBuiltin` -> `ClangBuiltin`).
+- Some processors might need the feature flag (`Has<DeprecatedFeature>`) added
+in their `UnsupportedFeatures` list.

README.md

@@ -123,4 +123,4 @@ You need to search for the instruction or operands with missing or incorrect val
   ```
 
 - If certain target features (e.g. architecture extensions) were removed from LLVM or you want to add your own,
-checkout [DeprecatedFeatures.md](DeprecatedFeatures.md).
+checkout [AddExtensions.md](AddExtensions.md).

llvm/lib/Target/AArch64/AArch64.td

@@ -1395,6 +1395,7 @@ def TuneAmpere1B : SubtargetFeature<"ampere1b", "ARMProcFamily", "Ampere1B",
                                     FeatureLdpAlignedOnly,
                                     FeatureStpAlignedOnly]>;
 
+
 def ProcessorFeatures {
   list<SubtargetFeature> A53  = [HasV8_0aOps, FeatureCRC, FeatureCrypto,
                                  FeatureFPARMv8, FeatureNEON, FeaturePerfMon];
@@ -1467,35 +1468,56 @@ def ProcessorFeatures {
                                      FeatureSVE, FeatureComplxNum];
   list<SubtargetFeature> Carmel   = [HasV8_2aOps, FeatureNEON, FeatureCrypto,
                                      FeatureFullFP16];
+
+  // Capstone addition:
+  // Proprietary system instructions are added to all Apple processors.
+  // Even if we don't know if they are actually supported.
+
   list<SubtargetFeature> AppleA7  = [HasV8_0aOps, FeatureCrypto, FeatureFPARMv8,
-                                     FeatureNEON,FeaturePerfMon, FeatureAppleA7SysReg];
+                                     FeatureNEON,FeaturePerfMon, FeatureAppleA7SysReg,
+                                     FeatureAppleSys];
   list<SubtargetFeature> AppleA10 = [HasV8_0aOps, FeatureCrypto, FeatureFPARMv8,
                                      FeatureNEON, FeaturePerfMon, FeatureCRC,
-                                     FeatureRDM, FeaturePAN, FeatureLOR, FeatureVH];
+                                     FeatureRDM, FeaturePAN, FeatureLOR, FeatureVH,
+                                     FeatureAppleSys];
+
+  // Capstone addition:
+  // Note about the Mul53 extension. According to https://gist.github.com/TrungNguyen1909/5b323edda9a21550a1621af506e8ce5f
+  // The mul53 instructions are use in Apple's H10 processor (part of AirPots according to apple.fandom.com).
+  // This processor doesn't exist in LLVM. But the reference claims H10 is equivalent to A11.
   list<SubtargetFeature> AppleA11 = [HasV8_2aOps, FeatureCrypto, FeatureFPARMv8,
-                                     FeatureNEON, FeaturePerfMon, FeatureFullFP16];
+                                     FeatureNEON, FeaturePerfMon, FeatureFullFP16,
+                                     FeatureMUL53, FeatureAppleSys];
   list<SubtargetFeature> AppleA12 = [HasV8_3aOps, FeatureCrypto, FeatureFPARMv8,
                                      FeatureNEON, FeaturePerfMon, FeatureFullFP16];
   list<SubtargetFeature> AppleA13 = [HasV8_4aOps, FeatureCrypto, FeatureFPARMv8,
                                      FeatureNEON, FeaturePerfMon, FeatureFullFP16,
-                                     FeatureFP16FML, FeatureSHA3];
+                                     FeatureFP16FML, FeatureSHA3, FeatureAppleSys];
+
+  // Capstone addition AMX: The A14 onwards are variants (same generation)
+  // of the Apple M series processors.
+  // To my knowledge it is not documented if those processors actually support AMX,
+  // but we add it here as feature anyways. Simply because it is too much work
+  // adding a model for the Apple M series processors. Capstone currently
+  // doesn't care about the LLVM processor definitions.
   list<SubtargetFeature> AppleA14 = [HasV8_4aOps, FeatureCrypto, FeatureFPARMv8,
                                      FeatureNEON, FeaturePerfMon, FeatureFRInt3264,
                                      FeatureSpecRestrict, FeatureSSBS, FeatureSB,
                                      FeaturePredRes, FeatureCacheDeepPersist,
                                      FeatureFullFP16, FeatureFP16FML, FeatureSHA3,
-                                     FeatureAltFPCmp];
+                                     FeatureAltFPCmp, FeatureAMX, FeatureAppleSys];
   list<SubtargetFeature> AppleA15 = [HasV8_6aOps, FeatureCrypto, FeatureFPARMv8,
                                      FeatureNEON, FeaturePerfMon, FeatureSHA3,
-                                     FeatureFullFP16, FeatureFP16FML];
+                                     FeatureFullFP16, FeatureFP16FML, FeatureAMX,
+                                     FeatureAppleSys];
   list<SubtargetFeature> AppleA16 = [HasV8_6aOps, FeatureCrypto, FeatureFPARMv8,
                                      FeatureNEON, FeaturePerfMon, FeatureSHA3,
                                      FeatureFullFP16, FeatureFP16FML,
-                                     FeatureHCX];
+                                     FeatureHCX, FeatureAMX, FeatureAppleSys];
   list<SubtargetFeature> AppleA17 = [HasV8_6aOps, FeatureCrypto, FeatureFPARMv8,
                                      FeatureNEON, FeaturePerfMon, FeatureSHA3,
                                      FeatureFullFP16, FeatureFP16FML,
-                                     FeatureHCX];
+                                     FeatureHCX, FeatureAMX, FeatureAppleSys];
   list<SubtargetFeature> ExynosM3 = [HasV8_0aOps, FeatureCRC, FeatureCrypto,
                                      FeaturePerfMon];
   list<SubtargetFeature> ExynosM4 = [HasV8_2aOps, FeatureCrypto, FeatureDotProd,