chore: add more docs

Author: Chronostasys

immix/llvm/memory_manager.cpp

@@ -1,3 +1,10 @@
+/*
+  LLVM memory manager for Pivot Lang
+  
+  This is very muck a work in progress. 
+  We are using this to get immix working with JIT.
+*/
+
 #include "llvm-c/ExecutionEngine.h"
 #include "llvm/ExecutionEngine/SectionMemoryManager.h"
 #include "llvm-c/Core.h"

immix/llvm/plimmix.cpp

@@ -4,11 +4,20 @@
 #include "llvm/Support/Compiler.h"
 #include "plimmixprinter.cpp"
 #include "plimmix_pass.cpp"
+#include "llvm/Passes/PassBuilder.h"
+#include "llvm/Passes/PassPlugin.h"
+
+#include "llvm-c/Types.h"
+#include "llvm-c/Transforms/PassBuilder.h"
 
 using namespace llvm;
 
 namespace
 {
+    /*
+        This is the GC strategy for immix.
+        It is used to register our immix GC with LLVM.
+    */
     class LLVM_LIBRARY_VISIBILITY PLImmixGC : public GCStrategy
     {
     public:
@@ -29,17 +38,16 @@ extern "C" void LLVMLinkPLImmixGC()
 }
 #include "llvm-c/Transforms/PassManagerBuilder.h"
 
-extern "C" void add_module_pass(llvm::legacy::PassManagerBase * PB) {
+extern "C" void add_module_pass(llvm::legacy::PassManagerBase *PB) {
     PB->add(new ImmixLegacy());
 
 }
-#include "llvm/Passes/PassBuilder.h"
-#include "llvm/Passes/PassPlugin.h"
-
-#include "llvm-c/Types.h"
-#include "llvm-c/Transforms/PassBuilder.h"
+/*
+    param: opt opt level
 
-// param: opt opt level
+    The new LLVM Pass Manager does not have official C bindings yet.
+    So we have to write one ourselves.
+*/
 extern "C" void run_module_pass(LLVMModuleRef  M, int opt) {
     // These must be declared in this order so that they are destroyed in the
     // correct order due to inter-analysis-manager references.
@@ -92,6 +100,9 @@ extern "C" void run_module_pass(LLVMModuleRef  M, int opt) {
 }
 
 
+/*
+    Shadow stack implementation for immix. (used in JIT mode, but may not work now)
+*/
 extern "C"
 {
     /// The map for a single function's stack frame.  One of these is

immix/llvm/plimmix_pass.cpp

@@ -1,3 +1,8 @@
+/*
+  Some LLVM passes helpful for
+  integrating immix with LLVM
+*/
+
 #include "llvm/IR/PassManager.h"
 #include "llvm/IR/IRBuilder.h"
 #include "llvm/Transforms/Utils/ModuleUtils.h"
@@ -10,6 +15,7 @@ using namespace llvm;
 namespace
 {
   void immixPassLogic(Module &M);
+  // The new pass manager plugin
   class ImmixPass : public PassInfoMixin<ImmixPass>
   {
     static char ID;
@@ -23,6 +29,24 @@ namespace
     return PreservedAnalyses::all();
   }
 
+  /*
+    This pass helps integrate immix with LLVM.
+
+    It does the following:
+    - Sets the GC name to "plimmix" for all functions
+    - Adds a call to immix_gc_init in the global constructor
+    - Adds a global variable declaration for the module stack map
+
+    However, it does not generate the stack map. This is done by the
+    immix compiler plugin.
+
+    Also note that mauch more work is needed to get immix working with
+    LLVM. Besides the pass, you need to:
+    - Implement visit functions for all complex types
+    - insert stack roots for all heap pointers
+    - replace all malloc calls with immix::alloc
+    ...
+  */
   void immixPassLogic(Module &M)
   {
     for (auto FB = M.functions().begin(), FE = M.functions().end(); FB != FE; ++FB)
@@ -51,6 +75,8 @@ namespace
     // appendToCompilerUsed(M, gc_init_f);
     appendToGlobalCtors(M, gc_init_f, 1000);
   }
+
+  // The old pass manager plugin
   struct ImmixLegacy : public ModulePass
   {
     static char ID;

immix/llvm/plimmixprinter.cpp

@@ -1,9 +1,22 @@
 #include "llvm/CodeGen/GCMetadataPrinter.h"
 #include "llvm/Support/Compiler.h"
+#include "llvm/CodeGen/AsmPrinter.h"
+#include "llvm/IR/Function.h"
+#include "llvm/IR/DataLayout.h"
+// #include "llvm/Target/TargetAsmInfo.h"
+#include "llvm/Target/TargetMachine.h"
+#include "llvm/IR/GCStrategy.h"
+#include "llvm/CodeGen/GCMetadata.h"
+#include "llvm/MC/MCStreamer.h"
+#include "llvm/Target/TargetLoweringObjectFile.h"
+#include "llvm/MC/MCAsmInfo.h"
 using namespace llvm;
 
 namespace
 {
+  /*
+    Stackmap printer for immix.
+  */
   class LLVM_LIBRARY_VISIBILITY PLImmixGCPrinter : public GCMetadataPrinter
   {
   public:
@@ -17,22 +30,16 @@ namespace
       P("plimmix", "pivot-lang immix garbage collector.");
 }
 
-#include "llvm/CodeGen/AsmPrinter.h"
-#include "llvm/IR/Function.h"
-#include "llvm/IR/DataLayout.h"
-// #include "llvm/Target/TargetAsmInfo.h"
-#include "llvm/Target/TargetMachine.h"
-#include "llvm/IR/GCStrategy.h"
-#include "llvm/CodeGen/GCMetadata.h"
-#include "llvm/MC/MCStreamer.h"
-#include "llvm/Target/TargetLoweringObjectFile.h"
-#include "llvm/MC/MCAsmInfo.h"
 
 void PLImmixGCPrinter::beginAssembly(Module &M, GCModuleInfo &Info, AsmPrinter &AP)
 {
   // Nothing to do.
 }
 
+
+/*
+  We need to emit the stack map in the data section.
+*/
 void PLImmixGCPrinter::finishAssembly(Module &M, GCModuleInfo &Info, AsmPrinter &AP)
 {
   unsigned IntPtrSize = AP.getPointerSize();