Changes between Version 14 and Version 15 of Commentary/Compiler/CodeGen


Ignore:
Timestamp:
Jun 13, 2007 10:39:13 AM (7 years ago)
Author:
Michael D. Adams
Comment:

Expanded section on how the modules are structured

Legend:

Unmodified
Added
Removed
Modified
  • Commentary/Compiler/CodeGen

    v14 v15  
    5252  ret::                    Direct return address     
    5353  vtbl::                   Vector table 
    54   <n>_alt::                Case alternative (tag n) 
     54  ''n''_alt::              Case alternative (tag ''n'') 
    5555  dflt::                   Default case alternative 
    5656  btm::                    Large bitmap vector 
     
    7171 
    7272== Modules == 
    73 === Primary Modules === 
    74   {{{CodeGen}}}:: Top level. Called by the {{{HscMain}}} module. 
    75   {{{CgClosure}}}:: Called by {{{CodeGen}}} for top level bindings. 
    76   {{{CgCon}}}:: Called by {{{CodeGen}}} for data types. 
    77  
    78   {{{CgExpr}}}:: Called by {{{CgClosure}}} and {{{CgCon}}}. 
    79     Since everything in STG is an expression, almost everything branches off from here. 
    80  
    81   {{{CgMonad}}}:: The monad that most of codeGen operates inside 
    82    * Reader 
    83    * State 
    84    * (could be Writer?) 
    85    * fork 
    86    * flatten 
     73=== {{{CodeGen}}} === 
     74Top level, only exports {{{codeGen}}}. 
     75 
     76Called from {{{HscMain}}} for each module that needs to be converted from Stg to Cmm. 
     77 
     78For each such module {{{codeGen}}} does three things: 
     79 * {{{cgTopBinding}}} for the {{{StgBinding}}} 
     80 * {{{cgTyCon}}} for the {{{TyCon}}} (These are constructors not constructor calls). 
     81 * {{{mkModuleInit}}} for the module 
     82 
     83{{{mkModuleInit}}} generates several boilerplate initialization functions 
     84that: 
     85 * regiser the module, 
     86 * creates an Hpc table, 
     87 * setup its profiling info ({{{InitConstCentres}}}, code coverage info {{{initHpc}}}), and 
     88 * calls the initialization functions of the modules it imports. 
     89 
     90If neither SCC profiling or HPC are used, 
     91then the initialization code short circuits to return. 
     92 
     93If the module has already been initialized, 
     94the initialization function just returns. 
     95 
     96The Ghc.TopHandler and Ghc.Prim modules get special treatment. 
     97 
     98{{{cgTopBinding}}} is a small wrapper around {{{cgTopRhs}}} 
     99which in turn disptaches to: 
     100 * {{{cgTopRhsCons}}} for {{{StgRhsCons}}} 
     101   (these are bindings of constructor applications not constructors themselves) and 
     102 * {{{cgTopRhsClosure}}} for {{{StgRhsClosure}}}. 
     103 
     104{{{cgTopRhsCons}}} and {{{cgTopRhsClosure}}} are located in {{{CgCon}}} and {{{CgClosure}}} 
     105which are the primary modules called by {{{CodeGen}}}. 
     106 
     107=== {{{CgCon}}} === 
     108TODO 
     109 
     110=== {{{CgClosure}}} === 
     111TODO 
     112 
     113=== {{{CgMonad}}} === 
     114The monad that most of codeGen operates inside 
     115 * Reader 
     116 * State 
     117 * (could be Writer?) 
     118 * fork 
     119 * flatten 
     120 
     121=== {{{CgExpr}}} === 
     122Called by {{{CgClosure}}} and {{{CgCon}}}. 
     123 
     124Since everything in STG is an expression, almost everything branches off from here. 
     125 
     126This module exports only one function {{{cgExpr}}}, 
     127which for the most part just dispatches 
     128to other functions to handle each specific constructor in {{{StgExpr}}}. 
     129 
     130Here are the core functions that each constructor is disptached to 
     131(though some may have little helper functions called in addition to the core function): 
     132 {{{StgApp}}}:: Calls to {{{cgTailCall}}} in {{{CgTailCall}}} 
     133 {{{StgConApp}}}:: Calls to {{{cgReturnDataCon}}} in {{{CgCon}}} 
     134 {{{StgLit}}}:: 
     135   Calls to {{{cgLit}}} in {{{CgUtil}}} 
     136    and {{{performPrimReturn}}} in {{{CgTailCall}}} 
     137 {{{StgOpApp}}}:: 
     138   Is a bit more complicated see below. 
     139 {{{StgCase}}}:: Calls to {{{cgCase}}} in {{{CgCase}}} 
     140 {{{StgLet}}}:: Calls to {{{cgRhs}}} in {{{CgExpr}}} 
     141 {{{StgLetNoEscape}}}:: 
     142   Calls to {{{cgLetNoEscapeBindings}}} in {{{CgExpr}}}, but with a little bit of wrapping 
     143   by {{{nukeDeadBindings}}} and {{{saveVolatileVarsAndRegs}}}. 
     144 {{{StgSCC}}}:: Calls to  {{{emitSetCCC}}} in {{{CgProf}}} 
     145 {{{StgTick}}}:: Calls to {{{cgTickBox}}} in {{{CgHpc}}} 
     146 {{{StgLam}}}:: 
     147   Does not have a case because it is only for {{{CoreToStg}}}'s work. 
     148 
     149Some of these cases call to functions defined in {{{cgExpr}}}. 
     150This is because they need a little bit of wrapping and processing 
     151before calling out to their main worker function. 
     152 
     153 {{{cgRhs}}}:: 
     154 * For {{{StgRhsCon}}} calls out to {{{buildDynCon}}} in {{{CgCon}}}. 
     155 * For {{{StgRhsClosure}}} calls out to {{{mkRhsClosure}}}. 
     156   In turn, {{{mkRhsClosure}}} calls out to {{{cgStdRhsClosure}}} for selectors and thunks, 
     157   and calls out to {{{cgRhsClosure}}} in the default case. 
     158   Both these are defined in {{{CgClosure}}}. 
     159 
     160 {{{cgLetNoEscapeBindings}}}:: 
     161 * Wraps a call to {{{cgLetNoEscapeRhs}}} with {{{addBindsC}}} 
     162   depending on whether it is called on a recursive or a non-recursive binding. 
     163   In turn {{{cgLetNoEscapeRhs}}} wraps {{{cgLetNoEscapeClosure}}} 
     164   defined in {{{CgLetNoEscapeClosure}}}. 
     165 
     166{{{StgOpApp}}} has a number of sub-cases. 
     167 * {{{StgFCallOp}}} 
     168 * {{{StgPrimOp}}} of a TagToEnumOp 
     169 * {{{StgPrimOp}}} that is primOpOutOfLine 
     170 * {{{StgPrimOp}}} that returns Void 
     171 * {{{StgPrimOp}}} that returns a single primitive 
     172 * {{{StgPrimOp}}} that returns an unboxed tuple 
     173 * {{{StgPrimOp}}} that returns an enumeration type 
     174 
     175(It appears that non-foreign-call, inline PrimOps are not allowed to return complex data types (e.g. a |Maybe|), but this fact needs to be verified.) 
     176 
     177Each of these cases centers around one of these three core calls: 
     178 * {{{emitForeignCall}}} in {{{CgForeignCall}}} 
     179 * {{{tailCallPrimOp}}} in {{{CgTailCall}}} 
     180 * {{{cgPrimOp}}} in {{{CgPrimOp}}} 
     181 
     182There is also a little bit of argument and return marshelling with the following functions 
     183 Argument marshelling:: 
     184   {{{shimForeignCallArg}}}, {{{getArgAmods}}} 
     185 Return marshelling:: 
     186   {{{dataReturnConvPrim}}}, {{{primRepToCgRep}}}, {{{newUnboxedTupleRegs}}} 
     187 Performing the return:: 
     188   {{{emitReturnInstr}}}, {{{performReturn}}}, 
     189   {{{returnUnboxedTuple}}}, {{{ccallReturnUnboxedTuple}}} 
     190 
     191In summary the modules that get called in order to handle a specific expression case are: 
     192==== Also called for top level bindings by {{{CodeGen}}} ==== 
     193 {{{CgCon}}}:: for {{{StgConApp}}} and the {{{StgRhsCon}}} part of {{{StgLet}}} 
     194 {{{CgClosure}}}:: for the {{{StgRhsClosure}}} part of {{{StgLet}}} 
     195 
     196==== Core code generation ==== 
     197 {{{CgTailCall}}}:: for {{{StgApp}}}, {{{StgLit}}}, and {{{StgOpApp}}} 
     198 {{{CgPrimOp}}}:: for {{{StgOpApp}}} 
     199 {{{CgLetNoEscapeClosure}}}:: for {{{StgLetNoEscape}}} 
     200 {{{CgCase}}}:: for {{{StgCase}}} 
     201 
     202==== Profiling and Code coverage related ==== 
     203 {{{CgProf}}}:: for {{{StgSCC}}} 
     204 {{{CgHpc}}}:: for {{{StgTick}}} 
     205 
     206==== Utility modules that happen to have the functions for code generation ==== 
     207 {{{CgForeignCall}}}:: for {{{StgOpApp}}} 
     208 {{{CgUtil}}}:: for {{{cgLit}}} 
     209 
     210Note that the first two are 
     211the same modules that are called for top level bindings by {{{CodeGen}}}, 
     212and the last two are really utility modules, 
     213but they happen to have the functions 
     214needed for those code generation cases. 
    87215 
    88216=== Memory and Register Management === 
     
    123251   Part of ClosureInfo but kept separate to "keep nhc happy." 
    124252 {{{CgUtils}}}:: TODO 
     253 {{{CgInfoTbls}}}:: TODO 
    125254 
    126255=== Special runtime support === 
     
    131260   Code generation for GranSim (GRAN) and parallel (PAR). 
    132261   All the functions are dead stubs except {{{granYield}}} and {{{granFetchAndReschedule}}}. 
    133  
    134 === Not yet classified === 
    135 Please help classify these if you know what they are. 
    136  
    137  CgInfoTbls 
    138  
    139  CgCase 
    140  CgLetNoEscape 
    141