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

Jun 13, 2007 10:39:13 AM (8 years ago)
Michael D. Adams

Expanded section on how the modules are structured


  • 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 
    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. 
    78   {{{CgExpr}}}:: Called by {{{CgClosure}}} and {{{CgCon}}}. 
    79     Since everything in STG is an expression, almost everything branches off from here. 
    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}}}. 
     76Called from {{{HscMain}}} for each module that needs to be converted from Stg to Cmm. 
     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 
     83{{{mkModuleInit}}} generates several boilerplate initialization functions 
     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. 
     90If neither SCC profiling or HPC are used, 
     91then the initialization code short circuits to return. 
     93If the module has already been initialized, 
     94the initialization function just returns. 
     96The Ghc.TopHandler and Ghc.Prim modules get special treatment. 
     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}}}. 
     104{{{cgTopRhsCons}}} and {{{cgTopRhsClosure}}} are located in {{{CgCon}}} and {{{CgClosure}}} 
     105which are the primary modules called by {{{CodeGen}}}. 
     107=== {{{CgCon}}} === 
     110=== {{{CgClosure}}} === 
     113=== {{{CgMonad}}} === 
     114The monad that most of codeGen operates inside 
     115 * Reader 
     116 * State 
     117 * (could be Writer?) 
     118 * fork 
     119 * flatten 
     121=== {{{CgExpr}}} === 
     122Called by {{{CgClosure}}} and {{{CgCon}}}. 
     124Since everything in STG is an expression, almost everything branches off from here. 
     126This module exports only one function {{{cgExpr}}}, 
     127which for the most part just dispatches 
     128to other functions to handle each specific constructor in {{{StgExpr}}}. 
     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. 
     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. 
     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}}}. 
     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}}}. 
     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 
     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.) 
     177Each of these cases centers around one of these three core calls: 
     178 * {{{emitForeignCall}}} in {{{CgForeignCall}}} 
     179 * {{{tailCallPrimOp}}} in {{{CgTailCall}}} 
     180 * {{{cgPrimOp}}} in {{{CgPrimOp}}} 
     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}}} 
     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}}} 
     196==== Core code generation ==== 
     197 {{{CgTailCall}}}:: for {{{StgApp}}}, {{{StgLit}}}, and {{{StgOpApp}}} 
     198 {{{CgPrimOp}}}:: for {{{StgOpApp}}} 
     199 {{{CgLetNoEscapeClosure}}}:: for {{{StgLetNoEscape}}} 
     200 {{{CgCase}}}:: for {{{StgCase}}} 
     202==== Profiling and Code coverage related ==== 
     203 {{{CgProf}}}:: for {{{StgSCC}}} 
     204 {{{CgHpc}}}:: for {{{StgTick}}} 
     206==== Utility modules that happen to have the functions for code generation ==== 
     207 {{{CgForeignCall}}}:: for {{{StgOpApp}}} 
     208 {{{CgUtil}}}:: for {{{cgLit}}} 
     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. 
    88216=== Memory and Register Management === 
    123251   Part of ClosureInfo but kept separate to "keep nhc happy." 
    124252 {{{CgUtils}}}:: TODO 
     253 {{{CgInfoTbls}}}:: TODO 
    126255=== Special runtime support === 
    131260   Code generation for GranSim (GRAN) and parallel (PAR). 
    132261   All the functions are dead stubs except {{{granYield}}} and {{{granFetchAndReschedule}}}. 
    134 === Not yet classified === 
    135 Please help classify these if you know what they are. 
    137  CgInfoTbls 
    139  CgCase 
    140  CgLetNoEscape