I documented this file, in an attempt to understand it, with a view toward

rewriting it.  I also vacuumed out all the commented-out code and
inaccurate comments, etc.

(We need to put the mapping information in a data structure so that we can
pass it out to the JIT, instead of automagically converting it to .byte
directives.)

llvm-svn: 6574

1 files changed, 73 insertions, 56 deletions

diff --git a/llvm/lib/Target/Sparc/MappingInfo.cpp b/llvm/lib/Target/Sparc/MappingInfo.cpp
index 757247874b4..66f2aa5538f 100644
--- a/llvm/lib/Target/Sparc/MappingInfo.cpp
+++ b/llvm/lib/Target/Sparc/MappingInfo.cpp
@@ -1,8 +1,16 @@
 //===- MappingInfo.cpp - create LLVM info and output to .s file ---------===//
 //
-// Create Map from LLVM BB and Instructions and Machine Instructions
-// and output the information as .byte directives to the .s file
-// Currently Sparc specific but will be extended for others later
+// This file contains a FunctionPass called getMappingInfoForFunction,
+// which creates two maps: one between LLVM Instructions and MachineInstrs,
+// and another between MachineBasicBlocks and MachineInstrs (the "BB TO
+// MI MAP").
+//
+// As a side effect, it outputs this information as .byte directives to
+// the assembly file. The output is designed to survive the SPARC assembler,
+// in order that the Reoptimizer may read it in from memory later when the
+// binary is loaded. Therefore, it may contain some hidden SPARC-architecture
+// dependencies. Currently this question is purely theoretical as the
+// Reoptimizer works only on the SPARC.
 //
 //===--------------------------------------------------------------------===//
 
@@ -15,10 +23,6 @@
 #include <map>
 using std::vector;
 
-
-// MappingInfo - This method collects mapping info 
-// for the mapping from LLVM to machine code.
-//
 namespace {
   class getMappingInfoForFunction : public FunctionPass { 
     std::ostream &Out;
@@ -46,24 +50,22 @@ namespace {
   };
 }
 
-
-//pass definition
+/// MappingInfoForFunction -- Static factory method: returns a new
+/// getMappingInfoForFunction Pass object.
 Pass *MappingInfoForFunction(std::ostream &out){
   return (new getMappingInfoForFunction(out));
 }
 
-//function definitions :
-//create and output maps to the .s file
+/// runOnFunction -- Builds up the maps for the given function and then
+/// writes them out as assembly code to the current output stream Out.
+/// This is an entry point to the pass, called by the PassManager.
 bool getMappingInfoForFunction::runOnFunction(Function &FI) {
-  
-  
-  //first create reference maps
-  //createFunctionKey(M);
+  // First we build up the maps.
   create_BB_to_MInumber_Key(FI);
   create_MI_to_number_Key(FI);
-  unsigned FunctionNo = Fkey[&(FI)];
+  unsigned FunctionNo = Fkey[&FI];
 
-  //now print out the maps
+  // Now, print out the maps.
   writePrologue("BB TO MI MAP", "BBMIMap", FunctionNo);
   writeBBToMImap(FI);
   writeEpilogue("BB TO MI MAP", "BBMIMap", FunctionNo);  
@@ -95,7 +97,8 @@ void getMappingInfoForFunction::writeEpilogue(const char *area,
       << FunctionNo << "\n\n\n\n";
 }
 
-//write out information as .byte directives
+/// writeNumber -- Write out the number X as a sequence of .byte
+/// directives to the current output stream Out.
 unsigned getMappingInfoForFunction::writeNumber(unsigned X) {
   unsigned i=0;
   do {
@@ -108,20 +111,31 @@ unsigned getMappingInfoForFunction::writeNumber(unsigned X) {
   return i;
 }
 
-//Assign a number to each Function 
+/// doInitialization -- Assign a number to each Function, as follows:
+/// Functions are numbered starting at 0 at the begin() of each Module.
+/// Functions which are External (and thus have 0 basic blocks) are not
+/// inserted into the maps, and are not assigned a number.  The side-effect
+/// of this method is to fill in Fkey to contain the mapping from Functions
+/// to numbers. (This method is called automatically by the PassManager.)
 bool getMappingInfoForFunction::doInitialization(Module &M) {
   unsigned i = 0;
-  for (Module::iterator FI = M.begin(), FE = M.end();
-       FI != FE; ++FI){
-    //dont count F with 0 BBs
-    if(FI->isExternal()) continue;
+  for (Module::iterator FI = M.begin(), FE = M.end(); FI != FE; ++FI) {
+    if (FI->isExternal()) continue;
     Fkey[FI] = i;
     ++i;
   }
   return false;
 }
-     
-//Assign a Number to each BB
+
+/// create_BB_to_MInumber_Key -- Assign a number to each MachineBasicBlock
+/// in the given Function, as follows: Numbering starts at zero in each
+/// Function. MachineBasicBlocks are numbered from begin() to end()
+/// in the Function's corresponding MachineFunction. Each successive
+/// MachineBasicBlock increments the numbering by the number of instructions
+/// it contains. The side-effect of this method is to fill in the instance
+/// variable BBkey with the mapping of MachineBasicBlocks to numbers. BBkey
+/// is keyed on MachineInstrs, so each MachineBasicBlock is represented
+/// therein by its first MachineInstr.
 void getMappingInfoForFunction::create_BB_to_MInumber_Key(Function &FI) {
   unsigned i = 0;
   MachineFunction &MF = MachineFunction::get(&FI);
@@ -133,7 +147,13 @@ void getMappingInfoForFunction::create_BB_to_MInumber_Key(Function &FI) {
   }
 }
 
-//Assign a number to each MI wrt beginning of the BB
+/// create_MI_to_number_Key -- Assign a number to each MachineInstr
+/// in the given Function with respect to its enclosing MachineBasicBlock, as
+/// follows: Numberings start at 0 in each MachineBasicBlock. MachineInstrs
+/// are numbered from begin() to end() in their MachineBasicBlock. Each
+/// MachineInstr is numbered, then the numbering is incremented by 1. The
+/// side-effect of this method is to fill in the instance variable MIkey
+/// with the mapping from MachineInstrs to numbers.
 void getMappingInfoForFunction::create_MI_to_number_Key(Function &FI) {
   MachineFunction &MF = MachineFunction::get(&FI);
   for (MachineFunction::iterator BI=MF.begin(), BE=MF.end(); BI != BE; ++BI) {
@@ -146,8 +166,13 @@ void getMappingInfoForFunction::create_MI_to_number_Key(Function &FI) {
   }
 }
 
-//BBtoMImap: contains F#, BB#, 
-//              MI#[wrt beginning of F], #MI in BB
+/// writeBBToMImap -- Output the BB TO MI MAP for the given function as
+/// assembly code to the current output stream. The BB TO MI MAP consists
+/// of a three-element tuple for each MachineBasicBlock in a function:
+/// first, the index of the MachineBasicBlock in the function; second,
+/// the number of the MachineBasicBlock in the function as computed by
+/// create_BB_to_MInumber_Key; and third, the number of MachineInstrs in
+/// the MachineBasicBlock.
 void getMappingInfoForFunction::writeBBToMImap(Function &FI){
   unsigned bb = 0;
   MachineFunction &MF = MachineFunction::get(&FI);  
@@ -155,47 +180,39 @@ void getMappingInfoForFunction::writeBBToMImap(Function &FI){
        BI != BE; ++BI, ++bb) {
     MachineBasicBlock &miBB = *BI;
     writeNumber(bb);
-    //Out << " BB: "<<(void *)BI<<"\n";
-    //for(int i=0; i<miBB.size(); ++i)
-    //Out<<*miBB[i]<<"\n";
-    writeNumber( BBkey[ miBB[0] ]);
+    writeNumber(BBkey[miBB[0]]);
     writeNumber(miBB.size());
   }
 }
 
-//LLVMtoMImap: contains F#, BB#, LLVM#, 
-//                           MIs[wrt to beginning of BB] 
+/// writeLLVMToMImap -- Output the LLVM I TO MI MAP for the given function
+/// as assembly code to the current output stream. The LLVM I TO MI MAP
+/// consists of a set of information for each BasicBlock in a Function,
+/// ordered from begin() to end(). The information for a BasicBlock consists
+/// of 1) its (0-based) index in the Function, 2) the number of LLVM
+/// Instructions it contains, and 3) information for each Instruction, in
+/// sequence from the begin() to the end() of the BasicBlock. The information
+/// for an Instruction consists of 1) its (0-based) index in the BasicBlock,
+/// 2) the number of MachineInstrs that correspond to that Instruction
+/// (as reported by MachineCodeForInstruction), and 3) the MachineInstr
+/// number calculated by create_MI_to_number_Key, for each of the
+/// MachineInstrs that correspond to that Instruction.
 void getMappingInfoForFunction::writeLLVMToMImap(Function &FI) {
 
-  unsigned bb =0;
-  for (Function::iterator BI = FI.begin(),  BE = FI.end(); 
+  unsigned bb = 0;
+  for (Function::iterator BI = FI.begin(), BE = FI.end(); 
        BI != BE; ++BI, ++bb) {
     unsigned li = 0;
     writeNumber(bb);
-    //std::cerr<<"BasicBlockNumber= "<<bb<<"\n";
-
-    //Out << "BB: "<<(void *)BI<<"\n";
     writeNumber(BI->size());
-    //std::cerr<<"BasicBlockSize  = "<<BI->size()<<"\n";
-
-    for (BasicBlock::iterator II = BI->begin(), 
-	   IE = BI->end(); II != IE; ++II, ++li) {
-    //Out << "I: "<<*II<<"\n";
-      MachineCodeForInstruction& miI = 
-	MachineCodeForInstruction::get(II);
-      
-      //do for each corr. MI
+    for (BasicBlock::iterator II = BI->begin(), IE = BI->end(); II != IE;
+         ++II, ++li) {
+      MachineCodeForInstruction& miI = MachineCodeForInstruction::get(II);
       writeNumber(li);
-      //std::cerr<<"InstructionNumber= "<<li<<"\n";
-
       writeNumber(miI.size());
-      //std::cerr<<"InstructionSize  = "<<miI.size()<<"\n";
-   
       for (MachineCodeForInstruction::iterator miII = miI.begin(), 
-	     miIE = miI.end(); miII != miIE; ++miII){
-	//Out << "MI: "<<**miII<<"\n";
-	writeNumber(MIkey[*miII]);
-        //std::cerr<<"MachineInstruction= "<<MIkey[*miII]<<"\n";
+           miIE = miI.end(); miII != miIE; ++miII) {
+	     writeNumber(MIkey[*miII]);
       }
     }
   }