-\section[codegen-intro]{Intro/background info for the code generator}
-
-\tr{NOTES.codeGen} LIVES!!!
-
-\begin{verbatim}
-=======================
-NEW! 10 Nov 93 Semi-tagging
-
-Rough idea
-
- case x of -- NB just a variable scrutinised
- [] -> ...
- (p:ps) -> ...p... -- eg. ps not used
-
-generates
-
- Node = a ptr to x
- while TRUE do { switch TAG(Node) {
-
- INDIRECTION_TAG : Node = Node[1]; break; -- Dereference indirection
-
- OTHER_TAG : adjust stack; push return address; ENTER(Node)
-
- 0 : adjust stack;
- JUMP( Nil_case )
-
- 1 : adjust stack;
- R2 := Node[2] -- Get ps
- JUMP( Cons_case )
- }
-
-* The "return address" is a vector table, which contains pointers to
- Nil_case and Cons_case.
-
-* The "adjust stack" in the case of OTHER_TAG is one word different to
- that in the case of a constructor tag (0,1,...), because it needs to
- take account of the return address. That's why the stack adjust
- shows up in the branches, rather than before the switch.
-
-* In the case of *unvectored* returns, the "return address" will be
- some code which switches on TagReg. Currently, the branches of the
- case at the return address have the code for the alternatives
- actually there:
-
- switch TagReg {
- 0 : code for nil case
- 1 : code for cons case
- }
-
-But with semi-tagging, we'll have to label each branch:
-
- switch TagReg {
- 0 : JUMP( Nil_case )
- 1 : JUMP( Cons_case )
- }
-
-So there's an extra jump. Boring. Boring. (But things are usually
-eval'd...in which case we save a jump.)
-
-* TAG is a macro which gets a "tag" from the info table. The tag
- encodes whether the thing is (a) an indirection, (b) evaluated
- constructor with tag N, or (c) something else. The "something else"
- usually indicates something unevaluated, but it might also include
- FETCH_MEs etc. Anything which must be entered.
-
-* Maybe we should get the info ptr out of Node, into a temporary
- InfoPtrReg, so that TAG and ENTER share the info-ptr fetch.
-
-* We only load registers which are live in the alternatives. So at
- the start of an alternative, either the unused fields *will* be in
- regs (if we came via enter/return) or they *won't* (if we came via
- the semi-tagging switch). If they aren't, GC had better not follow
- them. So we can't arrange that all live ptrs are neatly lined up in
- the first N regs any more. So GC has to take a liveness
- bit-pattern, not just a "number of live regs" number.
-
-* We need to know which of the constructors fields are live in the
- alternatives. Hence STG code has to be elaborated to keep live vars
- for each alternative, or to tag each bound-var in the alternatives
- with whether or not it is used.
-
-* The code generator needs to be able to construct unique labels for
- the case alternatives. (Previously this was done by the AbsC
- flattening pass.) Reason: we now have an explicit join point at the
- start of each alternative.
-
-* There's some question about how tags are mapped. Is 0 the first
- tag? (Good when switching on TagReg when there are only two
- constructors.) What is OTHER_TAG and INDIRECTION_TAG?
-
-* This whole deal can be freely mixed with un-semi-tagged code.
- There should be a compiler flag to control it.
-
-=======================
-Many of the details herein are moldy and dubious, but the general
-principles are still mostly sound.
-\end{verbatim}
-
-%************************************************************************
-%* *
-\subsection{LIST OF OPTIMISATIONS TO DO}
-%* *
-%************************************************************************
-
-\begin{itemize}
-\item
-Register return conventions.
-
-\item
-Optimisations for Enter when
- \begin{itemize}
- \item
- know code ptr, so don't indirect via Node
- \item
- know how many args
- \item
- top level closures don't load Node
- \end{itemize}
-\item
-Strings.
-
-\item
-Case of unboxed op with more than one alternative, should generate
-a switch or an if statement.
-\end{itemize}
-
-{\em Medium}
-
-\begin{itemize}
-\item
-Don't allocate constructors with no args.
-Instead have a single global one.
-
-\item
-Have global closures for all characters, and all small numbers.
-\end{itemize}
-
-
-{\em Small}
-
-\begin{itemize}
-\item
-When a closure is one of its own free variables, don't waste a field
-on it. Instead just use Node.
-\end{itemize}
-
-
-%************************************************************************
-%* *
-\subsection{ENTERING THE GARBAGE COLLECTOR}
-%* *
-%************************************************************************
-
-[WDP: OLD]
-
-There are the following ways to get into the garbage collector:
-
-\begin{verbatim}
-_HEAP_OVERFLOW_ReturnViaNode
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Used for the GC trap at closure entry.
-
- - Node is only live ptr
- - After GC, enter Node
-
-_HEAP_OVERFLOW_ReturnDirect0, _HEAP_OVERFLOW_ReturnDirect1, ...
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Used: for fast entry of functions, and
- case alternative where values are returned in regs
-
- - PtrReg1..n are live ptrs
- - ReturnReg points to start of code (before hp oflo check)
- - After GC, jump to ReturnReg
- - TagReg is preserved, in case this is an unvectored return
-
-
-_HEAP_OVERFLOW_CaseReturnViaNode
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- *** GRIP ONLY ***
-
-Used for case alternatives which return node in heap
-
- - Node is only live ptr
- - RetVecReg points to return vector
- - After GC, push RetVecReg and enter Node
-\end{verbatim}
-
-Exactly equivalent to @GC_ReturnViaNode@, preceded by pushing @ReturnVectorReg@.
-
-The only reason we re-enter Node is so that in a GRIP-ish world, the
-closure pointed to be Node is re-loaded into local store if necessary.
-
-%************************************************************************
-%* *
-\subsection{UPDATES}
-%* *
-%************************************************************************
-
-[New stuff 27 Nov 91]
-
-\subsubsection{Return conventions}
-%~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-When executing the update continuation code for a constructor,
-@RetVecReg@ points to the {\em beginning of} the return vector. This is to
-enable the update code to find the normal continuation code.
-(@RetVecReg@ is set up by the code which jumps to the update continuation
-code.)
-
-\subsubsection{Stack arrangement}
-%~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Each stack has a ``stack update ptr'', SuA and SuB, which point to the
-topmost word of the stack just after an update frame has been pushed.
-
-A standard update frame (on the B stack) looks like this
-(stack grows downward in this picture):
-
-\begin{verbatim}
- | |
- |---------------------------------------|
- | Saved SuA |
- |---------------------------------------|
- | Saved SuB |
- |---------------------------------------|
- | Pointer to closure to be updated |
- |---------------------------------------|
- | Pointer to Update return vector |
- |---------------------------------------|
-\end{verbatim}
-
-The SuB therefore points to the Update return vector component of the
-topmost update frame.
-
-A {\em constructor} update frame, which is pushed only by closures
-which know they will evaluate to a data object, looks just the
-same, but without the saved SuA pointer.
-
-\subsubsection{Pushing update frames}
-%~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-An update is pushed right at the start of the code for an updatable
-closure. But {\em after} the stack overflow check. (The B-stack oflo
-check should thereby include allowance for the update frame itself.)
-
-\subsubsection{Return vectors}
-%~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Every ``return address'' pushed on the stack by a boxed \tr{case} is a
-pointer to a vector of one or more pairs of code pointers:
-
-\begin{verbatim}
- ------> -----------------
- | Cont1 |
- |---------------|
- | Update1 |
- -----------------
- | Cont2 |
- |---------------|
- | Update2 |
- -----------------
- ...etc...
-\end{verbatim}
-
-Each pair consists of a {\em continuation} code pointer and an
-{\em update} code pointer.
-
-For data types with only one constructor, or too many constructors for
-vectoring, the return vector consists of a single pair.
-
-When the \tr{data} decl for each data type is compiled, as well as
-making info tables for each constructor, an update code sequence for
-each constructor (or a single one, if unvectored) is also created.
-
-ToDo: ** record naming convention for these code sequences somewhere **
-
-When the update code is entered, it uses the value stored in the
-return registers used by that constructor to update the thing pointed
-to by the update frame (all of which except for the return address is
-still on the B stack). If it can do an update in place (ie
-constructor takes 3 words or fewer) it does so.
-
-In the unvectored case, this code first has to do a switch on the tag,
-UNLESS the return is in the heap, in which case simply overwrite with
-an indirection to the thing Node points to.
-
-Tricky point: if the update code can't update in place it has to
-allocate a new object, by performing a heap-oflo check and jumping to
-the appropriate heap-overflow entry point depending on which RetPtr
-registers are live (just as when compiling a case alternative).
-
-When the update code is entered, a register @ReturnReg@ is assumed to
-contain the ``return address'' popped from the B stack. This is so
-that the update code can enter the normal continuation code when it is
-done.
-
-For standard update frames, the A and B stack update ptrs are restored
-from the saved versions before returning, too.
-
-\subsubsection{Update return vector}
-%~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Both standard and constructor update frames have as their topmost word
-a pointer to a static, fixed, update return vector.
-
-The ``continuation'' entry of each pair in this vector sets UpdReg to
-point to the thing to be updated (gotten from the update frame), pops
-the update frame, and returns to the ``update'' entry of the
-corresponding pair in the next return vector (now exposed on top of B
-stk).
-
-The ``update'' entry of each pair in this vector overwrites the thing
-to be updated with an indirection to the thing UpdReg points to, and
-then returns in the same was as the "continuation" entry above.
-
-There need to be enough pairs in the update return vector to cater for
-any constructor at all.
-
-
-*************************
-
-Things which need to be altered if you change the number of constructors
-which switches off vectored returns:
-\begin{verbatim}
- Extra cases in update return vector (file xxx)
- The value xxxx in yyyy.lhs
- others?
-\end{verbatim}
-**************************
-
-%************************************************************************
-%* *
-\subsection{HEAP OBJECTS}
-%* *
-%************************************************************************
-
-The heap consists of {\em closures}.
-A closure can be either:
-\begin{itemize}
-\item
-a {\em suspension}, which is an unevaluated thunk.
-\item
-a {\em constructed object} (or just constructor); created by let(recs) and
-by updating.
-\item
-a {\em partial application} (only updating creates these).
-\end{itemize}
-
-Closures are laid out with the {\em info pointer} at the lowest
-address (but see notes on the Global Address field for parallel
-system). [We don't try to localise knowledge of this! It is a royal
-pain having to cope with closures laid out backwards.]
-
-Ptr fields occur first (before non-ptr ones).
-
-Non-normal-form closures are always at least 3 words in size (excl
-global address), so they can be updated with a list cell (should they
-evaluate to that).
-
-Normal form (constructor) closures are always at least 2 words in size
-(excl global address), so they have room enough for forwarding ptrs
-during GC, and FETCHME boxes after flushing.
-
-1-word closures for normal-form closures in static space. Explain
-more.
-
-Ideally, the info pointer of a closure would point to...
-\begin{verbatim}
- |-------------|
- | info table |
- |-------------|
-info ptr ---> code
-\end{verbatim}
-
-But when C is the target code we can't guarantee the relative
-positions of code and data. So the info ptr points to
-\begin{verbatim}
- |-------------|
-info ptr ---->| ------------------------> code
- |-------------|
- | info table |
- |-------------|
-\end{verbatim}
-
-That is, there's an extra indirection involved; and the info table
-occurs AFTER the info pointer rather than before. The info table
-entries are ``reversed'' too, so that bigger negative offsets in the
-``usual'' case turn into bigger positive offsets.
-
-SUSPENSIONS
-
-The simplest form of suspension is
-\begin{verbatim}
- info-ptr, ptr free vars, non-ptr free vars
-\end{verbatim}
-
-where the info table for info-ptr gives
-\begin{itemize}
-\item
-the total number of words of free vars
-\item
-the number of words of ptr free vars (== number of ptr free vars)
-in its extra-info part.
-\end{itemize}
-
-Optimised versions omit the size info from the info table, and instead
-use specialised GC routines.
-
-
-%************************************************************************
-%* *
-\subsection{NAMING CONVENTIONS for compiled code}
-%* *
-%************************************************************************
-
-
-Given a top-level closure called f defined in module M,
-
-\begin{verbatim}
- _M_f_closure labels the closure itself
- (only for top-level (ie static) closures)
-
- _M_f_entry labels the slow entry point of the code
- _M_f_fast labels the fast entry point of the code
-
- _M_f_info labels the info pointer for the closure for f
- (NB the info ptr of a closure isn't public
- in the sense that these labels
- are. It is private to a module, and
- its name can be a secret.)
-\end{verbatim}
-
-These names are the REAL names that the linker sees. The initial underscores
-are attached by the C compiler.
-
-A non-top-level closure has the same names, but as well as the \tr{f}
-the labels have the unique number, so that different local closures
-which share a name don't get confused. The reason we need a naming
-convention at all is that with a little optimisation a tail call may
-jump direct to the fast entry of a locally-defined closure.
-
-\tr{f} may be a constructor, in the case of closures which are the curried
-versions of the constructor.
-
-For constructor closures, we have the following naming conventions, where
-the constructor is C defined in module M:
-
-\begin{verbatim}
- _M_C_con_info is the info ptr for the constructor
- _M_C_con_entry is the corresponding code entry point
-\end{verbatim}
-
-%************************************************************************
-%* *
-\subsection{ENTRY CONVENTIONS}
-%* *
-%************************************************************************
-
-\begin{description}
-\item[Constructor objects:]
- On entry to the code for a constructor (\tr{_M_C_con_entry}), Node
- points to the constructor object. [Even if the constructor has arity
- zero...]
-
-\item[Non-top-level suspensions (both fast and slow entries):]
- Node points to the closure.
-
-\item[Top-level suspensions, slow entry:]
- ReturnReg points to the slow entry point itself
-
-\item[..ditto, fast entry:]
- No entry convention
-\end{description}
-
-
-%************************************************************************
-%* *
-\subsection{CONSTRUCTOR RETURN CONVENTIONS}
-%* *
-%************************************************************************
-
-There is lots of excitement concerning the way in which constructors
-are returned to case expressions.
-
-{\em Simplest version}
-%=====================
-
-The return address on the stack points directly to some code. It
-expects:
-
-\begin{verbatim}
-Boxed objects:
- PtrReg1 points to the constructed value (in the heap) (unless arity=0)
- Tag contains its tag (unless # of constructors = 1)
-
-Unboxed Ints: IntReg contains the int
- Float: FloatReg contains the returned value
-\end{verbatim}
-
-{\em Small improvement: vectoring}
-%=================================
-
-If there are fewer than (say) 8 constructors in the type, the return
-address points to a vector of return addresses. The constructor does
-a vectored return. No CSwitch.
-
-Complication: updates. Update frames are built before the type of the
-thing which will be returned is known. Hence their return address
-UPDATE has to be able to handle anything (vectored and nonvectored).
-
-Hence the vector table goes BACKWARD from ONE WORD BEFORE the word
-pointed to by the return address.
-
-{\em Big improvement: contents in registers}
-%===========================================
-
-Constructor with few enough components (eg 8ish) return their
-arguments in registers. [If there is only one constructor in the
-type, the tag register can be pressed into service for this purpose.]
-
-Complication: updates. Update frames are built before the type of the
-thing which will be returned is known. Hence their return address
-UPDATE has to be able to handle anything.
-
-So, a return address is a pointer to a PAIR of return addresses (or
-maybe a pointer to some code immediately preceded by a pointer to some
-code).
-
-The ``main'' return address is just as before.
-
-The ``update'' return address expects just the same regs to be in use
-as the ``main'' address, BUT AS WELL the magic loc UpdPtr points to a
-closure to be updated. It carries out the update, and contines with
-the main return address.
-
-The ``main'' code for UPDATE just loads UpdPtr the thing to be
-updated, and returns to the "update" entry of the next thing on the
-stack.
-
-The ``update'' entry for UPDATE just overwrites the thing to be
-updated with an indirection to UpdPtr.
-
-These two improvements can be combined orthogonally.
-
-
-%************************************************************************
-%* *
-\subsection{REGISTERS}
-%* *
-%************************************************************************
-
-Separate registers for
-\begin{verbatim}
- C stack (incl interrupt handling, if this is not done on
- another stk) (if interrupts don't mangle the C stack,
- we could save it for most of the time and reuse the
- register)
-
- Arg stack
- Basic value and control stack
- These two grow towards each other, so they are each
- other's limits!
-
- Heap pointer
-\end{verbatim}
-
-And probably also
-\begin{verbatim}
- Heap limit
-\end{verbatim}
-
-
-%************************************************************************
-%* *
-\subsection{THE OFFSET SWAMP}
-%* *
-%************************************************************************
-
-There are THREE kinds of offset:
-\begin{description}
-\item[virtual offsets:]
-
- start at 1 at base of frame, and increase towards top of stack.
-
- don't change when you adjust sp/hp.
-
- independent of stack direction.
-
- only exist inside the code generator, pre Abstract C
-
- for multi-word objects, the offset identifies the word of the
- object with smallest offset
-
-\item[reg-relative offsets:]
-
- start at 0 for elt to which sp points, and increase ``into the
- interesting stuff.''
-
- Specifically, towards
- \begin{itemize}
- \item
- bottom of stack (for SpA, SpB)
- \item
- beginning of heap (for Hp)
- \item
- end of closure (for Node)
- \end{itemize}
-
- offset for a particular item changes when you adjust sp.
-
- independent of stack direction.
-
- exist in abstract C CVal and CAddr addressing modes
-
- for multi-word objects, the offset identifies the word of the
- object with smallest offset
-
-\item[real offsets:]
-
- either the negation or identity of sp-relative offset.
-
- start at 0 for elt to which sp points, and either increase or
- decrease towards bottom of stk, depending on stk direction
-
- exist in real C, usually as a macro call passing an sp-rel offset
-
- for multi-word objects, the offset identifies the word of the
- object with lowest address
-\end{description}
-
-%************************************************************************
-%* *
-\subsection{STACKS}
-%* *
-%************************************************************************
-
-There are two stacks, as in the STG paper.
-\begin{description}
-\item[A stack:]
-contains only closure pointers. Its stack ptr is SpA.
-
-\item[B stack:]
-contains basic values, return addresses, update frames.
-Its stack ptr is SpB.
-\end{description}
-
-SpA and SpB point to the topmost allocated word of stack (though they
-may not be up to date in the middle of a basic block).
-
-\subsubsection{STACK ALLOCATION}
-
-A stack and B stack grow towards each other, so they overflow when
-they collide.
-
-The A stack grows downward; the B stack grows upward. [We'll try to
-localise stuff which uses this info.]
-
-We can check for stack {\em overflow} not just at the start of a basic
-block, but at the start of an entire expression evaluation. The
-high-water marks of case-expression alternatives can be max'd.
-
-Within the code for a closure, the ``stack frame'' is deemed to start
-with the last argument taken by the closure (ie the one deepest in the
-stack). Stack slots are can then be identified by ``virtual offsets''
-from the base of the frame; the bottom-most word of the frame has
-offset 1.
-
-For multi-word slots (B stack only) the offset identifies the word
-with the smallest virtual offset. [If B grows upward, this is the word
-with the lowest physical address too.]
-
-Since there are two stacks, a ``stack frame'' really consists of two
-stack frames, one on each stack.
-
-For each stack, we keep track of the following:
-
-\begin{verbatim}
-* virtSp virtual stack ptr offset of topmost occupied stack slot
- (initialised to 0 if no args)
-
-* realSp real stack ptr offset of real stack ptr reg
- (initialised to 0 if no args)
-
-* tailSp tail-call ptr offset of topmost slot to be retained
- at next tail call, excluding the
- argument to the tail call itself
-
-* hwSp high-water mark largest value taken by virtSp
- in this closure body
-\end{verbatim}
-
-The real stack pointer is (for now) only adjusted at the tail call itself,
-at which point it is made to point to the topmost occupied word of the stack.
-
-We can't always adjust it at the beginning, because we don't
-necessarily know which tail call will be made (a conditional might
-intervene). So stuff is actually put on the stack ``above'' the stack
-pointer. This is ok because interrupts are serviced on a different
-stack.
-
-The code generator works entirely in terms of stack {\em virtual
-offsets}. The conversion to real addressing modes is done solely when
-we look up a binding. When we move a stack pointer, the offsets of
-variables currently bound to stack offsets in the environment will
-change. We provide operations in the @cgBindings@ type to perform
-this offset-change (to wit, @shiftStkOffsets@), leaving open whether
-it is done pronto, or kept separate and applied to lookups.
-
-Stack overflow checking takes place at the start of a closure body, using
-the high-water mark information gotten from the closure body.
-
-
-%************************************************************************
-%* *
-\subsection{HEAP ALLOCATION}
-%* *
-%************************************************************************
-
-Heap ptr reg (Hp) points to the last word of allocated space (and not
-to the first word of free space).
-
-The heap limit register (HpLim) points to the last word of available
-space.
-
-A basic block allocates a chunk of heap called a ``heap frame''.
-The word of the frame nearest to the previously-allocated stuff
-has virtual offset 1, and offsets increase from 1 to the size of the
-frame in words.
-
-Closures are allocated with their code pointers having the lowest virtual
-offset.
-
-NOTE: this means that closures are only laid out with code ptr at
-lowest PHYSICAL address if the heap grows upwards.
-
-Heap ptr reg is moved at the beginning of a basic block to account for
-the allocation of the whole frame. At this time a heap exhaustion
-check is made (has the heap ptr gone past the heap limit?). In the
-basic block, indexed accesses off the heap ptr fill in this newly
-allocated block. [Bias to RISC here: no cheap auto-inc mode, and free
-indexing.]
-
-We maintain the following information during code generation:
-
-\begin{verbatim}
-* virtHp virtual heap ptr offset of last word
- of the frame allocated so far
- Starts at 0 and increases.
-* realHp virtual offset of
- the real Hp register
-\end{verbatim}
-
-Since virtHp only ever increases, it doubles as the heap high water mark.
-
-\subsubsection{BINDINGS}
-
-The code generator maintains info for each name about where it is.
-Each variable maps to:
-
-\begin{verbatim}
- - its kind
-
- - its volatile location:- a temporary variable
- - a virtual heap offset n, meaning the
- ADDRESS OF a word in the current
- heap frame
- - absent
-
- - its stable location: - a virtual stack offset n, meaning the
- CONTENTS OF an object in the
- current stack frame
- - absent
-\end{verbatim}
-
-\subsubsection{ENTERING AN OBJECT}
-
-When a closure is entered at the normal entry point, the magic locs
-\begin{verbatim}
- Node points to the closure (unless it is a top-level closure)
- ReturnReg points to the code being jumped to
-\end{verbatim}
-At the fast entry point, Node is still set up, but ReturnReg may not be.
-[Not sure about this.]
projects / ghc-hetmet.git / commitdiff