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