Doc fixups

suite/auto-sync/README.md

@@ -36,8 +36,8 @@ pip install -e .
 #### Clone Capstones LLVM fork and build `llvm-tblgen`
 
 ```bash
-git clone https://github.com/capstone-engine/llvm-capstone vendor/llvm_root/
-cd vendor/llvm_root/llvm-capstone
+git clone https://github.com/capstone-engine/llvm-capstone <capstone-root>/suite/auto-sync/vendor/llvm_root/
+cd <capstone-root>/suite/auto-sync/vendor/llvm_root/llvm-capstone
 git checkout auto-sync
 mkdir build
 cd build

suite/auto-sync/RefactorGuide.md

@@ -33,7 +33,10 @@ Note:
 	- Clone and build `llvm-tblgen` (see docs)
   - Quickly check options of the updater `ASUpdater -h`
 	- Add Arch name in `Target.py`
-	- In [llvm-capstone](https://github.com/capstone-engine/llvm-capstone) handle arch in `PrinterCapstone.cpp::decoderEmitterEmitFieldFromInstruction()` (add decoder function)
+	- In [llvm-capstone](https://github.com/capstone-engine/llvm-capstone) handle arch in `PrinterCapstone.cpp::decoderEmitterEmitDecodeInstruction()` (add decoder function)
+	  [!NOTE] Architecture specific code generation.
+		There are several oddities of architectures which require slightly different generated code.
+		If you search through `PrinterCapstone.cpp` for architecture names like `AArch64`, `ARM`, or `Sparc` you can see how these are handled.
 	- Generate: `ASUpdater -s IncGen -a ARCH`
 		- Errors? Check if the error message tells you what to do. If no hint exists, ask us.
 	- Check if `inc` files in `build` look good.
@@ -70,11 +73,19 @@ Note:
 		- If in doubt, check the original C++ file in the LLVM repo.
 - ### Make it build
 	- Add `ARCHLinkage.h` and the functions in the `InstPrinter.c`, `ArchDisassembler.c`.
+		- Explanation: The idea behind `ARCHLinkage.h` is to separate the Capstone and LLVM code, at least loosely, into compile units.
+			So the LLVM and Capstone code can at some point live in their own object files. This is not yet implemented, but
+			we try to keep them from becoming too entangled.
 	- Add essential code in `ARCHMapping.c`. Esential is everything **not** releated to details.
 	- If unsure how to do Capstone <-> LLVM code things, always check LoongArch. If LoongArch doesn't handle this case, check Mips, SystemZ
 - ### Run tests & Fixing bugs
 	- Update regression MC tests: Map LLVM `mattr` and `mcpu` names to the CS identifiers if necessary. -> Edit the `mcupdater.json` config file.
   - Update tests: `ASUpdater -s MCUpdate -a Arch -w`
+		- It can happen that `MCUpdate` doesn't generate any tests. This means LLVM has no disassembly tests for this architecture.
+			You can add your arch to `use_assembly_tests` in `mcupdater.json` to do so.
+			Keep in mind that some tests can later fail even though they are correct.
+			The compiler can assemble an instruction to a semantically equivalent, but syntactically different one.
+			This syntactic mismatch can later make those tests fail in Capstone.
 	- Run MC tests: `cstest tests/MC/Arch`
 - ### Add details
 	- Effectively copy behavior from `LoongArchMapping.c` or `SystemZMapping.c` but change values.