+ documentation

compiler/cgobj.pas

@@ -21,6 +21,7 @@
 
  ****************************************************************************
 }
+{# @abstract(Abstract code generator unit) }
 unit cgobj;
 
 {$i defines.inc}
@@ -35,9 +36,17 @@ unit cgobj;
 
     type
        talignment = (AM_NATURAL,AM_NONE,AM_2BYTE,AM_4BYTE,AM_8BYTE);
-
+       
+        
+       {# @abstract(Abstract code generator) 
+          This class implements an abstract instruction generator. Some of 
+          the methods of this class are generic, while others must
+          be overriden for all new processors which will be supported
+          by Free Pascal.
+       }   
        tcg = class
           scratch_register_array_pointer : aword;
+          {# List of currently unused scratch registers }
           unusedscratchregisters : tregisterset;
 
           alignment : talignment;
@@ -45,16 +54,28 @@ unit cgobj;
           {                 basic routines                 }
           constructor create;
 
+          {# Emit a label to the instruction stream. }
           procedure a_label(list : taasmoutput;l : tasmlabel);virtual;
 
-          { allocates register r by inserting a pai_realloc record }
+          {# Allocates register r by inserting a pai_realloc record }
           procedure a_reg_alloc(list : taasmoutput;r : tregister);
-          { deallocates register r by inserting a pa_regdealloc record}
+          {# Deallocates register r by inserting a pa_regdealloc record}
           procedure a_reg_dealloc(list : taasmoutput;r : tregister);
 
-          { returns a register for use as scratch register }
+          {# @abstract(Returns a register for use as scratch register) 
+             This routine returns a register which can be used by
+             the code generator as a scratch register. Since
+             scratch_registers are scarce resources, the register
+             should be freed by calling @link(get_scratch_reg) as 
+             soon as it is no longer required.
+          }
           function get_scratch_reg(list : taasmoutput) : tregister;
-          { releases a scratch register }
+          {# @abstract(Releases a scratch register) 
+          
+             Releases a scratch register.
+             This routine is used to free a register which
+             was previously allocated using @link(get_scratch_reg).
+          }
           procedure free_scratch_reg(list : taasmoutput;r : tregister);
 
           {************************************************}
@@ -95,10 +116,52 @@ unit cgobj;
           { left to right), this allows to move the parameter to    }
           { register, if the cpu supports register calling          }
           { conventions                                             }
+          
+          {# Pass a parameter, which is located in a register, to a routine.
+             
+             This routine should push/send the parameter to the routine, as
+             required by the specific processor ABI. This must be overriden for
+             each CPU target.
+             
+             @param(size size of the operand in the register)
+             @param(r register source of the operand)
+             @param(nr parameter number (starting from one) of routine (from left to right))
+          }   
           procedure a_param_reg(list : taasmoutput;size : tcgsize;r : tregister;nr : longint);virtual; abstract;
+          {# Pass a parameter, which is a constant, to a routine.
+             
+             A generic version is provided.
+             
+             @param(size size of the operand in constant)
+             @param(a value of constant to send)
+             @param(nr parameter number (starting from one) of routine (from left to right))
+          }   
           procedure a_param_const(list : taasmoutput;size : tcgsize;a : aword;nr : longint);virtual;
+          {# Pass the value of a parameter, which is located in memory, to a routine.
+             
+             A generic version is provided.
+             
+             @param(size size of the operand in constant)
+             @param(r Memory reference of value to send)
+             @param(nr parameter number (starting from one) of routine (from left to right))
+          }   
           procedure a_param_ref(list : taasmoutput;size : tcgsize;const r : treference;nr : longint);virtual;
+          {# Pass the value of a parameter, which can be located either in a register or memory location, 
+             to a routine.
+             
+             A generic version is provided.
+             
+             @param(l location of the operand to send)
+             @param(nr parameter number (starting from one) of routine (from left to right))
+          }   
           procedure a_param_loc(list : taasmoutput;const l : tlocation;nr : longint);
+          {# Pass the address of a reference to a routine.
+             
+             A generic version is provided.
+             
+             @param(r reference to get address from)
+             @param(nr parameter number (starting from one) of routine (from left to right))
+          }   
           procedure a_paramaddr_ref(list : taasmoutput;const r : treference;nr : longint);virtual;
 
           {**********************************}
@@ -121,6 +184,9 @@ unit cgobj;
               second the destination
           }
 
+          {# Emits instruction to call the method specified by symbol name @var(s) with offset
+             to symbol in @var(offset). This routine must be overriden for each new target cpu.
+          }
           procedure a_call_name(list : taasmoutput;const s : string;
             offset : longint);virtual; abstract;
 
@@ -207,21 +273,54 @@ unit cgobj;
           {********************************************************}
           { these methods can be overriden for extra functionality }
 
-          { the following methods do nothing: }
+          {# Emits instructions which should be emitted when entering 
+             a routine declared as @var(interrupt). The default
+             behavior does nothing, should be overriden as required.
+          }
           procedure g_interrupt_stackframe_entry(list : taasmoutput);virtual;
+          
+          {# Emits instructions which should be emitted when exiting
+             a routine declared as @var(interrupt). The default
+             behavior does nothing, should be overriden as required.
+          }
           procedure g_interrupt_stackframe_exit(list : taasmoutput);virtual;
-
+    
+          {# Emits instructions when compilation is done in profile
+             mode (this is set as a command line option). The default
+             behavior does nothing, should be overriden as required.
+          }
           procedure g_profilecode(list : taasmoutput);virtual;
+          
+          {# Emits the call to the stack checking routine of
+             the runtime library. The default behavior 
+             does not need to be modified, as it is generic
+             for all platforms.
+          }
           procedure g_stackcheck(list : taasmoutput;stackframesize : longint);virtual;
 
           procedure g_maybe_loadself(list : taasmoutput);virtual; abstract;
-          { copies len bytes from the source to destination, if }
-          { loadref is true, it assumes that it first must load }
-          { the source address from the memory location where   }
-          { source points to                                    }
+          {# This should emit the opcode to copy len bytes from the source 
+             to destination, if loadref is true, it assumes that it first must load 
+             the source address from the memory location where   
+             source points to.
+             
+             It must be overriden for each new target processor.
+             
+             @param(source Source reference of copy)
+             @param(dest Destination reference of copy)
+             @param(delsource Indicates if the source reference's resources should be freed)
+             @param(loadref Is the source reference a pointer to the actual source (TRUE), is it the actual source address (FALSE))
+             
+          }
           procedure g_concatcopy(list : taasmoutput;const source,dest : treference;len : aword;delsource,loadref : boolean);virtual; abstract;
 
-          { generates range checking code for a node }
+          {# Generates range checking code. It is to note
+             that this routine does not need to be overriden,
+             as it takes care of everything.
+             
+             @param(p Node which contains the value to check)
+             @param(todef Type definition of node to range check)
+          }
           procedure g_rangecheck(list: taasmoutput; const p: tnode;
             const todef: tdef); virtual;
 
@@ -1557,7 +1656,10 @@ finalization
 end.
 {
   $Log$
-  Revision 1.11  2002-04-06 18:10:42  jonas
+  Revision 1.12  2002-04-07 09:12:46  carl
+  + documentation
+
+  Revision 1.11  2002/04/06 18:10:42  jonas
     * several powerpc-related additions and fixes
 
   Revision 1.10  2002/04/04 19:05:54  peter