ghc/compiler/codeGen/ClosureInfo.lhs

   1 %
   2 % (c) The GRASP/AQUA Project, Glasgow University, 1992-1998
   3 %
   4 % $Id: ClosureInfo.lhs,v 1.34 1999/03/04 17:52:08 simonm Exp $
   5 %
   6 \section[ClosureInfo]{Data structures which describe closures}
   7
   8 Much of the rationale for these things is in the ``details'' part of
   9 the STG paper.
  10
  11 \begin{code}
  12 module ClosureInfo (
  13         ClosureInfo, LambdaFormInfo, SMRep,     -- all abstract
  14         StandardFormInfo,
  15
  16         EntryConvention(..),
  17
  18         mkClosureLFInfo, mkConLFInfo, mkSelectorLFInfo,
  19         mkApLFInfo, mkLFImported, mkLFArgument, mkLFLetNoEscape,
  20         UpdateFlag,
  21
  22         closureSize, closureNonHdrSize,
  23         closureGoodStuffSize, closurePtrsSize,
  24         slopSize,
  25
  26         layOutDynClosure, layOutDynCon, layOutStaticClosure,
  27         layOutStaticNoFVClosure,
  28         mkVirtHeapOffsets,
  29
  30         nodeMustPointToIt, getEntryConvention,
  31         FCode, CgInfoDownwards, CgState,
  32
  33         blackHoleOnEntry,
  34
  35         staticClosureRequired,
  36         slowFunEntryCodeRequired, funInfoTableRequired,
  37
  38         closureName, infoTableLabelFromCI, fastLabelFromCI,
  39         closureLabelFromCI,
  40         entryLabelFromCI,
  41         closureLFInfo, closureSMRep, closureUpdReqd,
  42         closureSingleEntry, closureSemiTag,
  43         isStandardFormThunk,
  44         GenStgArg,
  45
  46         isToplevClosure,
  47         closureTypeDescr,               -- profiling
  48
  49         isStaticClosure,
  50         allocProfilingMsg,
  51         blackHoleClosureInfo,
  52         maybeSelectorInfo,
  53         needsSRT
  54     ) where
  55
  56 #include "HsVersions.h"
  57
  58 import AbsCSyn          ( MagicId, node, VirtualHeapOffset, HeapOffset )
  59 import StgSyn
  60 import CgMonad
  61
  62 import Constants        ( mIN_UPD_SIZE, mIN_SIZE_NonUpdHeapObject,
  63                           mAX_SPEC_FUN_SIZE, mAX_SPEC_THUNK_SIZE, mAX_SPEC_CONSTR_SIZE )
  64 import CgRetConv        ( assignRegs )
  65 import CLabel           ( CLabel, mkStdEntryLabel, mkFastEntryLabel,
  66                           mkInfoTableLabel,
  67                           mkConInfoTableLabel, mkStaticClosureLabel,
  68                           mkBlackHoleInfoTableLabel,
  69                           mkStaticInfoTableLabel, mkStaticConEntryLabel,
  70                           mkConEntryLabel, mkClosureLabel,
  71                           mkSelectorInfoLabel, mkSelectorEntryLabel,
  72                           mkApInfoTableLabel, mkApEntryLabel,
  73                           mkReturnPtLabel
  74                         )
  75 import CmdLineOpts      ( opt_SccProfilingOn, opt_OmitBlackHoling,
  76                           opt_Parallel )
  77 import Id               ( Id, idType, getIdArity )
  78 import DataCon          ( DataCon, dataConTag, fIRST_TAG,
  79                           isNullaryDataCon, isTupleCon, dataConName
  80                         )
  81 import IdInfo           ( ArityInfo(..) )
  82 import Name             ( Name, isExternallyVisibleName, nameUnique )
  83 import PprType          ( getTyDescription )
  84 import PrimRep          ( getPrimRepSize, separateByPtrFollowness, PrimRep )
  85 import SMRep            -- all of it
  86 import Type             ( isUnLiftedType, Type )
  87 import BasicTypes       ( TopLevelFlag(..) )
  88 import Util             ( mapAccumL )
  89 import Outputable
  90 \end{code}
  91
  92 The ``wrapper'' data type for closure information:
  93
  94 \begin{code}
  95 data ClosureInfo
  96   = MkClosureInfo
  97         Name                    -- The thing bound to this closure
  98         LambdaFormInfo          -- info derivable from the *source*
  99         SMRep                   -- representation used by storage manager
 100 \end{code}
 101
 102 %************************************************************************
 103 %*                                                                      *
 104 \subsection[ClosureInfo-datatypes]{Data types for closure information}
 105 %*                                                                      *
 106 %************************************************************************
 107
 108 %************************************************************************
 109 %*                                                                      *
 110 \subsubsection[LambdaFormInfo-datatype]{@LambdaFormInfo@: source-derivable info}
 111 %*                                                                      *
 112 %************************************************************************
 113
 114 \begin{code}
 115 data LambdaFormInfo
 116   = LFReEntrant         -- Reentrant closure; used for PAPs too
 117         Type            -- Type of closure    (ToDo: remove)
 118         TopLevelFlag    -- True if top level
 119         !Int            -- Arity
 120         !Bool           -- True <=> no fvs
 121
 122   | LFCon               -- Constructor
 123         DataCon         -- The constructor
 124         Bool            -- True <=> zero arity
 125
 126   | LFTuple             -- Tuples
 127         DataCon         -- The tuple constructor
 128         Bool            -- True <=> zero arity
 129
 130   | LFThunk             -- Thunk (zero arity)
 131         Type            -- Type of the thunk   (ToDo: remove)
 132         TopLevelFlag
 133         !Bool           -- True <=> no free vars
 134         Bool            -- True <=> updatable (i.e., *not* single-entry)
 135         StandardFormInfo
 136
 137   | LFArgument          -- Used for function arguments.  We know nothing about
 138                         -- this closure.  Treat like updatable "LFThunk"...
 139
 140   | LFImported          -- Used for imported things.  We know nothing about this
 141                         -- closure.  Treat like updatable "LFThunk"...
 142                         -- Imported things which we do know something about use
 143                         -- one of the other LF constructors (eg LFReEntrant for
 144                         -- known functions)
 145
 146   | LFLetNoEscape       -- See LetNoEscape module for precise description of
 147                         -- these "lets".
 148         Int             -- arity;
 149
 150   | LFBlackHole         -- Used for the closures allocated to hold the result
 151
 152                         -- of a CAF.  We want the target of the update frame to
 153                         -- be in the heap, so we make a black hole to hold it.
 154
 155
 156 data StandardFormInfo   -- Tells whether this thunk has one of a small number
 157                         -- of standard forms
 158
 159   = NonStandardThunk    -- No, it isn't
 160
 161   | SelectorThunk
 162        Int              -- 0-origin offset of ak within the "goods" of
 163                         -- constructor (Recall that the a1,...,an may be laid
 164                         -- out in the heap in a non-obvious order.)
 165
 166 {- A SelectorThunk is of form
 167
 168      case x of
 169        con a1,..,an -> ak
 170
 171    and the constructor is from a single-constr type.
 172 -}
 173
 174   | ApThunk
 175         Int             -- arity
 176
 177 {- An ApThunk is of form
 178
 179         x1 ... xn
 180
 181    The code for the thunk just pushes x2..xn on the stack and enters x1.
 182    There are a few of these (for 1 <= n <= MAX_SPEC_AP_SIZE) pre-compiled
 183    in the RTS to save space.
 184 -}
 185
 186 \end{code}
 187
 188 %************************************************************************
 189 %*                                                                      *
 190 \subsection[ClosureInfo-construction]{Functions which build LFInfos}
 191 %*                                                                      *
 192 %************************************************************************
 193
 194 @mkClosureLFInfo@ figures out the appropriate LFInfo for the closure.
 195
 196 \begin{code}
 197 mkClosureLFInfo :: Id           -- The binder
 198                 -> TopLevelFlag -- True of top level
 199                 -> [Id]         -- Free vars
 200                 -> UpdateFlag   -- Update flag
 201                 -> [Id]         -- Args
 202                 -> LambdaFormInfo
 203
 204 mkClosureLFInfo bndr top fvs upd_flag args@(_:_)  -- Non-empty args
 205   = LFReEntrant (idType bndr) top (length args) (null fvs)
 206
 207 mkClosureLFInfo bndr top fvs ReEntrant []
 208   = LFReEntrant (idType bndr) top 0 (null fvs)
 209
 210 mkClosureLFInfo bndr top fvs upd_flag []
 211 #ifdef DEBUG
 212   | isUnLiftedType ty = pprPanic "mkClosureLFInfo" (ppr bndr <+> ppr ty)
 213 #endif
 214   | otherwise
 215   = LFThunk ty top (null fvs) (isUpdatable upd_flag) NonStandardThunk
 216   where
 217     ty = idType bndr
 218 \end{code}
 219
 220 @mkConLFInfo@ is similar, for constructors.
 221
 222 \begin{code}
 223 mkConLFInfo :: DataCon -> LambdaFormInfo
 224
 225 mkConLFInfo con
 226   = -- the isNullaryDataCon will do this: ASSERT(isDataCon con)
 227     (if isTupleCon con then LFTuple else LFCon) con (isNullaryDataCon con)
 228
 229 mkSelectorLFInfo rhs_ty offset updatable
 230   = LFThunk rhs_ty NotTopLevel False updatable (SelectorThunk offset)
 231
 232 mkApLFInfo rhs_ty upd_flag arity
 233   = LFThunk rhs_ty NotTopLevel (arity == 0) (isUpdatable upd_flag)
 234         (ApThunk arity)
 235 \end{code}
 236
 237 Miscellaneous LF-infos.
 238
 239 \begin{code}
 240 mkLFArgument    = LFArgument
 241 mkLFBlackHole   = LFBlackHole
 242 mkLFLetNoEscape = LFLetNoEscape
 243
 244 mkLFImported :: Id -> LambdaFormInfo
 245 mkLFImported id
 246   = case getIdArity id of
 247       ArityExactly 0    -> LFThunk (idType id)
 248                                 TopLevel True{-no fvs-}
 249                                 True{-updatable-} NonStandardThunk
 250       ArityExactly n    -> LFReEntrant (idType id) TopLevel n True  -- n > 0
 251       other             -> LFImported   -- Not sure of exact arity
 252 \end{code}
 253
 254 %************************************************************************
 255 %*                                                                      *
 256 \subsection[ClosureInfo-sizes]{Functions about closure {\em sizes}}
 257 %*                                                                      *
 258 %************************************************************************
 259
 260 \begin{code}
 261 closureSize :: ClosureInfo -> HeapOffset
 262 closureSize cl_info@(MkClosureInfo _ _ sm_rep)
 263   = fixedHdrSize + closureNonHdrSize cl_info
 264
 265 closureNonHdrSize :: ClosureInfo -> Int
 266 closureNonHdrSize cl_info@(MkClosureInfo _ lf_info sm_rep)
 267   = tot_wds + computeSlopSize tot_wds sm_rep (closureUpdReqd cl_info)
 268     --ToDo: pass lf_info?
 269   where
 270     tot_wds = closureGoodStuffSize cl_info
 271
 272 closureGoodStuffSize :: ClosureInfo -> Int
 273 closureGoodStuffSize (MkClosureInfo _ _ sm_rep)
 274   = let (ptrs, nonptrs) = sizes_from_SMRep sm_rep
 275     in  ptrs + nonptrs
 276
 277 closurePtrsSize :: ClosureInfo -> Int
 278 closurePtrsSize (MkClosureInfo _ _ sm_rep)
 279   = let (ptrs, _) = sizes_from_SMRep sm_rep
 280     in  ptrs
 281
 282 -- not exported:
 283 sizes_from_SMRep :: SMRep -> (Int,Int)
 284 sizes_from_SMRep (GenericRep       ptrs nonptrs _)   = (ptrs, nonptrs)
 285 sizes_from_SMRep (StaticRep        ptrs nonptrs _)   = (ptrs, nonptrs)
 286 sizes_from_SMRep ConstantRep                         = (0, 0)
 287 sizes_from_SMRep BlackHoleRep                        = (0, 0)
 288 \end{code}
 289
 290 Computing slop size.  WARNING: this looks dodgy --- it has deep
 291 knowledge of what the storage manager does with the various
 292 representations...
 293
 294 Slop Requirements:
 295 \begin{itemize}
 296 \item
 297 Updateable closures must be @mIN_UPD_SIZE@.
 298         \begin{itemize}
 299         \item
 300         Indirections require 1 word
 301         \item
 302         Appels collector indirections 2 words
 303         \end{itemize}
 304 THEREFORE: @mIN_UPD_SIZE = 2@.
 305
 306 \item
 307 Collectable closures which are allocated in the heap
 308 must be @mIN_SIZE_NonUpdHeapObject@.
 309
 310 Copying collector forward pointer requires 1 word
 311
 312 THEREFORE: @mIN_SIZE_NonUpdHeapObject = 1@
 313 \end{itemize}
 314
 315 Static closures have an extra ``static link field'' at the end, but we
 316 don't bother taking that into account here.
 317
 318 \begin{code}
 319 slopSize cl_info@(MkClosureInfo _ lf_info sm_rep)
 320   = computeSlopSize (closureGoodStuffSize cl_info) sm_rep
 321          (closureUpdReqd cl_info)
 322
 323 computeSlopSize :: Int -> SMRep -> Bool -> Int
 324
 325 computeSlopSize tot_wds (StaticRep _ _ _) True          -- Updatable
 326   = max 0 (mIN_UPD_SIZE - tot_wds)
 327 computeSlopSize tot_wds (StaticRep _ _ _) False
 328   = 0                                   -- non updatable, non-heap object
 329 computeSlopSize tot_wds (GenericRep _ _ _) True         -- Updatable
 330   = max 0 (mIN_UPD_SIZE - tot_wds)
 331 computeSlopSize tot_wds (GenericRep _ _ _) False
 332   = max 0 (mIN_SIZE_NonUpdHeapObject - tot_wds)
 333 computeSlopSize tot_wds ConstantRep _
 334   = 0
 335 computeSlopSize tot_wds BlackHoleRep _                  -- Updatable
 336   = max 0 (mIN_UPD_SIZE - tot_wds)
 337 \end{code}
 338
 339 %************************************************************************
 340 %*                                                                      *
 341 \subsection[layOutDynClosure]{Lay out a dynamic closure}
 342 %*                                                                      *
 343 %************************************************************************
 344
 345 \begin{code}
 346 layOutDynClosure, layOutStaticClosure
 347         :: Name                     -- STG identifier of this closure
 348         -> (a -> PrimRep)           -- how to get a PrimRep for the fields
 349         -> [a]                      -- the "things" being layed out
 350         -> LambdaFormInfo           -- what sort of closure it is
 351         -> (ClosureInfo,            -- info about the closure
 352             [(a, VirtualHeapOffset)])   -- things w/ offsets pinned on them
 353
 354 layOutDynClosure name kind_fn things lf_info
 355   = (MkClosureInfo name lf_info sm_rep,
 356      things_w_offsets)
 357   where
 358     (tot_wds,            -- #ptr_wds + #nonptr_wds
 359      ptr_wds,            -- #ptr_wds
 360      things_w_offsets) = mkVirtHeapOffsets sm_rep kind_fn things
 361     sm_rep = chooseDynSMRep lf_info tot_wds ptr_wds
 362 \end{code}
 363
 364 A wrapper for when used with data constructors:
 365
 366 \begin{code}
 367 layOutDynCon :: DataCon
 368              -> (a -> PrimRep)
 369              -> [a]
 370              -> (ClosureInfo, [(a,VirtualHeapOffset)])
 371
 372 layOutDynCon con kind_fn args
 373   = layOutDynClosure (dataConName con) kind_fn args (mkConLFInfo con)
 374 \end{code}
 375
 376 %************************************************************************
 377 %*                                                                      *
 378 \subsection[layOutStaticClosure]{Lay out a static closure}
 379 %*                                                                      *
 380 %************************************************************************
 381
 382 layOutStaticClosure is only used for laying out static constructors at
 383 the moment.
 384
 385 Static closures for functions are laid out using
 386 layOutStaticNoFVClosure.
 387
 388 \begin{code}
 389 layOutStaticClosure name kind_fn things lf_info
 390   = (MkClosureInfo name lf_info
 391         (StaticRep ptr_wds (tot_wds - ptr_wds) closure_type),
 392      things_w_offsets)
 393   where
 394     (tot_wds,            -- #ptr_wds + #nonptr_wds
 395      ptr_wds,            -- #ptr_wds
 396      things_w_offsets) = mkVirtHeapOffsets (StaticRep bot bot bot) kind_fn things
 397
 398     -- constructors with no pointer fields will definitely be NOCAF things.
 399     -- this is a compromise until we can generate both kinds of constructor
 400     -- (a normal static kind and the NOCAF_STATIC kind).
 401     closure_type = case lf_info of
 402                         LFCon _ _ | ptr_wds == 0 -> CONSTR_NOCAF
 403                         _ -> getStaticClosureType lf_info
 404
 405     bot = panic "layoutStaticClosure"
 406
 407 layOutStaticNoFVClosure :: Name -> LambdaFormInfo -> ClosureInfo
 408 layOutStaticNoFVClosure name lf_info
 409   = MkClosureInfo name lf_info (StaticRep 0 0 (getStaticClosureType lf_info))
 410 \end{code}
 411
 412 %************************************************************************
 413 %*                                                                      *
 414 \subsection[SMreps]{Choosing SM reps}
 415 %*                                                                      *
 416 %************************************************************************
 417
 418 \begin{code}
 419 chooseDynSMRep
 420         :: LambdaFormInfo
 421         -> Int -> Int           -- Tot wds, ptr wds
 422         -> SMRep
 423
 424 chooseDynSMRep lf_info tot_wds ptr_wds
 425   = let
 426          nonptr_wds = tot_wds - ptr_wds
 427          closure_type = getClosureType tot_wds ptr_wds nonptr_wds lf_info
 428     in
 429     case lf_info of
 430         LFTuple _ True -> ConstantRep
 431         LFCon _ True   -> ConstantRep
 432         _              -> GenericRep ptr_wds nonptr_wds closure_type
 433
 434 getStaticClosureType :: LambdaFormInfo -> ClosureType
 435 getStaticClosureType lf_info =
 436     case lf_info of
 437         LFCon con True        -> CONSTR_NOCAF
 438         LFCon con False       -> CONSTR
 439         LFReEntrant _ _ _ _   -> FUN
 440         LFTuple _ _           -> CONSTR
 441         LFThunk _ _ _ _ (SelectorThunk _) -> THUNK_SELECTOR
 442         LFThunk _ _ _ True _  -> THUNK
 443         LFThunk _ _ _ False _ -> FUN
 444         _                     -> panic "getClosureType"
 445
 446 -- we *do* get non-updatable top-level thunks sometimes.  eg. f = g
 447 -- gets compiled to a jump to g (if g has non-zero arity), instead of
 448 -- messing around with update frames and PAPs.  We set the closure type
 449 -- to FUN_STATIC in this case.
 450
 451 getClosureType :: Int -> Int -> Int -> LambdaFormInfo -> ClosureType
 452 getClosureType tot_wds ptrs nptrs lf_info =
 453     case lf_info of
 454         LFCon con True       -> CONSTR_NOCAF
 455
 456         LFCon con False
 457                 | tot_wds > 0 && tot_wds <= mAX_SPEC_CONSTR_SIZE -> CONSTR_p_n ptrs nptrs
 458                 | otherwise -> CONSTR
 459
 460         LFReEntrant _ _ _ _
 461                 | tot_wds > 0 && tot_wds <= mAX_SPEC_FUN_SIZE -> FUN_p_n ptrs nptrs
 462                 | otherwise -> FUN
 463
 464         LFTuple _ _
 465                 | tot_wds > 0 && tot_wds <= mAX_SPEC_CONSTR_SIZE -> CONSTR_p_n ptrs nptrs
 466                 | otherwise -> CONSTR
 467
 468         LFThunk _ _ _ _ (SelectorThunk _) -> THUNK_SELECTOR
 469
 470         LFThunk _ _ _ _ _
 471                 | tot_wds > 0 && tot_wds <= mAX_SPEC_THUNK_SIZE -> THUNK_p_n ptrs nptrs
 472                 | otherwise -> THUNK
 473
 474         _                    -> panic "getClosureType"
 475 \end{code}
 476
 477 %************************************************************************
 478 %*                                                                      *
 479 \subsection[mkVirtHeapOffsets]{Assigning heap offsets in a closure}
 480 %*                                                                      *
 481 %************************************************************************
 482
 483 @mkVirtHeapOffsets@ (the heap version) always returns boxed things with
 484 smaller offsets than the unboxed things, and furthermore, the offsets in
 485 the result list
 486
 487 \begin{code}
 488 mkVirtHeapOffsets :: SMRep      -- Representation to be used by storage manager
 489           -> (a -> PrimRep)     -- To be able to grab kinds;
 490                                 --      w/ a kind, we can find boxedness
 491           -> [a]                -- Things to make offsets for
 492           -> (Int,              -- *Total* number of words allocated
 493               Int,              -- Number of words allocated for *pointers*
 494               [(a, VirtualHeapOffset)])
 495                                 -- Things with their offsets from start of
 496                                 --  object in order of increasing offset
 497
 498 -- First in list gets lowest offset, which is initial offset + 1.
 499
 500 mkVirtHeapOffsets sm_rep kind_fun things
 501   = let (ptrs, non_ptrs)              = separateByPtrFollowness kind_fun things
 502         (wds_of_ptrs, ptrs_w_offsets) = mapAccumL computeOffset 0 ptrs
 503         (tot_wds, non_ptrs_w_offsets) = mapAccumL computeOffset wds_of_ptrs non_ptrs
 504     in
 505         (tot_wds, wds_of_ptrs, ptrs_w_offsets ++ non_ptrs_w_offsets)
 506   where
 507     computeOffset wds_so_far thing
 508       = (wds_so_far + (getPrimRepSize . kind_fun) thing,
 509          (thing, fixedHdrSize + wds_so_far)
 510         )
 511 \end{code}
 512
 513 %************************************************************************
 514 %*                                                                      *
 515 \subsection[ClosureInfo-4-questions]{Four major questions about @ClosureInfo@}
 516 %*                                                                      *
 517 %************************************************************************
 518
 519 Be sure to see the stg-details notes about these...
 520
 521 \begin{code}
 522 nodeMustPointToIt :: LambdaFormInfo -> FCode Bool
 523 nodeMustPointToIt lf_info
 524
 525   = case lf_info of
 526         LFReEntrant ty top arity no_fvs -> returnFC (
 527             not no_fvs ||   -- Certainly if it has fvs we need to point to it
 528             case top of { TopLevel -> False; _ -> True }
 529                     -- If it is not top level we will point to it
 530                     --   We can have a \r closure with no_fvs which
 531                     --   is not top level as special case cgRhsClosure
 532                     --   has been dissabled in favour of let floating
 533
 534                 -- For lex_profiling we also access the cost centre for a
 535                 -- non-inherited function i.e. not top level
 536                 -- the  not top  case above ensures this is ok.
 537             )
 538
 539         LFCon   _ zero_arity -> returnFC True
 540         LFTuple _ zero_arity -> returnFC True
 541
 542         -- Strictly speaking, the above two don't need Node to point
 543         -- to it if the arity = 0.  But this is a *really* unlikely
 544         -- situation.  If we know it's nil (say) and we are entering
 545         -- it. Eg: let x = [] in x then we will certainly have inlined
 546         -- x, since nil is a simple atom.  So we gain little by not
 547         -- having Node point to known zero-arity things.  On the other
 548         -- hand, we do lose something; Patrick's code for figuring out
 549         -- when something has been updated but not entered relies on
 550         -- having Node point to the result of an update.  SLPJ
 551         -- 27/11/92.
 552
 553         LFThunk _ _ no_fvs updatable NonStandardThunk
 554           -> returnFC (updatable || not no_fvs || opt_SccProfilingOn)
 555
 556           -- For the non-updatable (single-entry case):
 557           --
 558           -- True if has fvs (in which case we need access to them, and we
 559           --                should black-hole it)
 560           -- or profiling (in which case we need to recover the cost centre
 561           --             from inside it)
 562
 563         LFThunk _ _ no_fvs updatable some_standard_form_thunk
 564           -> returnFC True
 565           -- Node must point to any standard-form thunk.
 566
 567         LFArgument  -> returnFC True
 568         LFImported  -> returnFC True
 569         LFBlackHole -> returnFC True
 570                     -- BH entry may require Node to point
 571
 572         LFLetNoEscape _ -> returnFC False
 573 \end{code}
 574
 575 The entry conventions depend on the type of closure being entered,
 576 whether or not it has free variables, and whether we're running
 577 sequentially or in parallel.
 578
 579 \begin{tabular}{lllll}
 580 Closure Characteristics & Parallel & Node Req'd & Argument Passing & Enter Via \\
 581 Unknown                         & no & yes & stack      & node \\
 582 Known fun ($\ge$ 1 arg), no fvs         & no & no  & registers  & fast entry (enough args) \\
 583 \ & \ & \ & \                                           & slow entry (otherwise) \\
 584 Known fun ($\ge$ 1 arg), fvs    & no & yes & registers  & fast entry (enough args) \\
 585 0 arg, no fvs @\r,\s@           & no & no  & n/a        & direct entry \\
 586 0 arg, no fvs @\u@              & no & yes & n/a        & node \\
 587 0 arg, fvs @\r,\s@              & no & yes & n/a        & direct entry \\
 588 0 arg, fvs @\u@                 & no & yes & n/a        & node \\
 589
 590 Unknown                         & yes & yes & stack     & node \\
 591 Known fun ($\ge$ 1 arg), no fvs         & yes & no  & registers & fast entry (enough args) \\
 592 \ & \ & \ & \                                           & slow entry (otherwise) \\
 593 Known fun ($\ge$ 1 arg), fvs    & yes & yes & registers & node \\
 594 0 arg, no fvs @\r,\s@           & yes & no  & n/a       & direct entry \\
 595 0 arg, no fvs @\u@              & yes & yes & n/a       & node \\
 596 0 arg, fvs @\r,\s@              & yes & yes & n/a       & node \\
 597 0 arg, fvs @\u@                 & yes & yes & n/a       & node\\
 598 \end{tabular}
 599
 600 When black-holing, single-entry closures could also be entered via node
 601 (rather than directly) to catch double-entry.
 602
 603 \begin{code}
 604 data EntryConvention
 605   = ViaNode                             -- The "normal" convention
 606
 607   | StdEntry CLabel                     -- Jump to this code, with args on stack
 608
 609   | DirectEntry                         -- Jump directly, with args in regs
 610         CLabel                          --   The code label
 611         Int                             --   Its arity
 612         [MagicId]                       --   Its register assignments
 613                                         --      (possibly empty)
 614
 615 getEntryConvention :: Name              -- Function being applied
 616                    -> LambdaFormInfo    -- Its info
 617                    -> [PrimRep]         -- Available arguments
 618                    -> FCode EntryConvention
 619
 620 getEntryConvention name lf_info arg_kinds
 621  =  nodeMustPointToIt lf_info   `thenFC` \ node_points ->
 622     returnFC (
 623
 624     -- if we're parallel, then we must always enter via node.  The reason
 625     -- is that the closure may have been fetched since we allocated it.
 626
 627     if (node_points && opt_Parallel) then ViaNode else
 628
 629     -- Commented out by SDM after futher thoughts:
 630     --   - the only closure type that can be blackholed is a thunk
 631     --   - we already enter thunks via node (unless the closure is
 632     --     non-updatable, in which case why is it being re-entered...)
 633
 634     case lf_info of
 635
 636         LFReEntrant _ _ arity _ ->
 637             if arity == 0 || (length arg_kinds) < arity then
 638                 StdEntry (mkStdEntryLabel name)
 639             else
 640                 DirectEntry (mkFastEntryLabel name arity) arity arg_regs
 641           where
 642             (arg_regs, _) = assignRegs live_regs (take arity arg_kinds)
 643             live_regs = if node_points then [node] else []
 644
 645         LFCon con True{-zero_arity-}
 646               -- a real constructor.  Don't bother entering it, just jump
 647               -- to the constructor entry code directly.
 648                           -> --false:ASSERT (null arg_kinds)
 649                              -- Should have no args (meaning what?)
 650                              StdEntry (mkStaticConEntryLabel (dataConName con))
 651
 652         LFCon con False{-non-zero_arity-}
 653                           -> --false:ASSERT (null arg_kinds)
 654                              -- Should have no args (meaning what?)
 655                              StdEntry (mkConEntryLabel (dataConName con))
 656
 657         LFTuple tup zero_arity
 658                           -> --false:ASSERT (null arg_kinds)
 659                              -- Should have no args (meaning what?)
 660                              StdEntry (mkConEntryLabel (dataConName tup))
 661
 662         LFThunk _ _ _ updatable std_form_info
 663           -> if updatable
 664              then ViaNode
 665              else StdEntry (thunkEntryLabel name std_form_info updatable)
 666
 667         LFArgument  -> ViaNode
 668         LFImported  -> ViaNode
 669         LFBlackHole -> ViaNode  -- Presumably the black hole has by now
 670                                 -- been updated, but we don't know with
 671                                 -- what, so we enter via Node
 672
 673         LFLetNoEscape 0
 674           -> StdEntry (mkReturnPtLabel (nameUnique name))
 675
 676         LFLetNoEscape arity
 677           -> ASSERT(arity == length arg_kinds)
 678              DirectEntry (mkReturnPtLabel (nameUnique name)) arity arg_regs
 679          where
 680             (arg_regs, _) = assignRegs [] arg_kinds
 681             -- node never points to a LetNoEscape, see above --SDM
 682             --live_regs     = if node_points then [node] else []
 683     )
 684
 685 blackHoleOnEntry :: ClosureInfo -> Bool
 686
 687 -- Static closures are never themselves black-holed.
 688 -- Updatable ones will be overwritten with a CAFList cell, which points to a
 689 -- black hole;
 690 -- Single-entry ones have no fvs to plug, and we trust they don't form part
 691 -- of a loop.
 692
 693 blackHoleOnEntry (MkClosureInfo _ _ (StaticRep _ _ _)) = False
 694
 695 blackHoleOnEntry (MkClosureInfo _ lf_info _)
 696   = case lf_info of
 697         LFReEntrant _ _ _ _       -> False
 698         LFLetNoEscape _           -> False
 699         LFThunk _ _ no_fvs updatable _
 700           -> if updatable
 701              then not opt_OmitBlackHoling
 702              else not no_fvs
 703         other -> panic "blackHoleOnEntry"       -- Should never happen
 704
 705 isStandardFormThunk :: LambdaFormInfo -> Bool
 706
 707 isStandardFormThunk (LFThunk _ _ _ _ (SelectorThunk _)) = True
 708 isStandardFormThunk (LFThunk _ _ _ _ (ApThunk _))       = True
 709 isStandardFormThunk other_lf_info                       = False
 710
 711 maybeSelectorInfo (MkClosureInfo _ (LFThunk _ _ _ _
 712                         (SelectorThunk offset)) _) = Just offset
 713 maybeSelectorInfo _ = Nothing
 714
 715 -- Does this thunk's info table have an SRT?
 716
 717 needsSRT :: ClosureInfo -> Bool
 718 needsSRT (MkClosureInfo _ info _) =
 719   case info of
 720     LFThunk _ _ _ _ (SelectorThunk _) -> False  -- not for selectors
 721     LFThunk _ _ _ _ _   -> True
 722     LFReEntrant _ _ _ _ -> True
 723     _ -> False
 724 \end{code}
 725
 726 Avoiding generating entries and info tables
 727 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 728 At present, for every function we generate all of the following,
 729 just in case.  But they aren't always all needed, as noted below:
 730
 731 [NB1: all of this applies only to *functions*.  Thunks always
 732 have closure, info table, and entry code.]
 733
 734 [NB2: All are needed if the function is *exported*, just to play safe.]
 735
 736
 737 * Fast-entry code  ALWAYS NEEDED
 738
 739 * Slow-entry code
 740         Needed iff (a) we have any un-saturated calls to the function
 741         OR         (b) the function is passed as an arg
 742         OR         (c) we're in the parallel world and the function has free vars
 743                         [Reason: in parallel world, we always enter functions
 744                         with free vars via the closure.]
 745
 746 * The function closure
 747         Needed iff (a) we have any un-saturated calls to the function
 748         OR         (b) the function is passed as an arg
 749         OR         (c) if the function has free vars (ie not top level)
 750
 751   Why case (a) here?  Because if the arg-satis check fails,
 752   UpdatePAP stuffs a pointer to the function closure in the PAP.
 753   [Could be changed; UpdatePAP could stuff in a code ptr instead,
 754    but doesn't seem worth it.]
 755
 756   [NB: these conditions imply that we might need the closure
 757   without the slow-entry code.  Here's how.
 758
 759         f x y = let g w = ...x..y..w...
 760                 in
 761                 ...(g t)...
 762
 763   Here we need a closure for g which contains x and y,
 764   but since the calls are all saturated we just jump to the
 765   fast entry point for g, with R1 pointing to the closure for g.]
 766
 767
 768 * Standard info table
 769         Needed iff (a) we have any un-saturated calls to the function
 770         OR         (b) the function is passed as an arg
 771         OR         (c) the function has free vars (ie not top level)
 772
 773         NB.  In the sequential world, (c) is only required so that the function closure has
 774         an info table to point to, to keep the storage manager happy.
 775         If (c) alone is true we could fake up an info table by choosing
 776         one of a standard family of info tables, whose entry code just
 777         bombs out.
 778
 779         [NB In the parallel world (c) is needed regardless because
 780         we enter functions with free vars via the closure.]
 781
 782         If (c) is retained, then we'll sometimes generate an info table
 783         (for storage mgr purposes) without slow-entry code.  Then we need
 784         to use an error label in the info table to substitute for the absent
 785         slow entry code.
 786
 787 \begin{code}
 788 staticClosureRequired
 789         :: Name
 790         -> StgBinderInfo
 791         -> LambdaFormInfo
 792         -> Bool
 793 staticClosureRequired binder (StgBinderInfo arg_occ unsat_occ _ _ _)
 794                       (LFReEntrant _ top_level _ _)     -- It's a function
 795   = ASSERT( case top_level of { TopLevel -> True; other -> False } )
 796         -- Assumption: it's a top-level, no-free-var binding
 797     arg_occ             -- There's an argument occurrence
 798     || unsat_occ        -- There's an unsaturated call
 799     || isExternallyVisibleName binder
 800
 801 staticClosureRequired binder other_binder_info other_lf_info = True
 802
 803 slowFunEntryCodeRequired        -- Assumption: it's a function, not a thunk.
 804         :: Name
 805         -> StgBinderInfo
 806         -> EntryConvention
 807         -> Bool
 808 slowFunEntryCodeRequired binder (StgBinderInfo arg_occ unsat_occ _ _ _) entry_conv
 809   = arg_occ             -- There's an argument occurrence
 810     || unsat_occ        -- There's an unsaturated call
 811     || isExternallyVisibleName binder
 812     || (case entry_conv of { DirectEntry _ _ _ -> False; other -> True })
 813             {- The last case deals with the parallel world; a function usually
 814                as a DirectEntry convention, but if it doesn't we must generate slow-entry code -}
 815
 816 slowFunEntryCodeRequired binder NoStgBinderInfo _ = True
 817
 818 funInfoTableRequired
 819         :: Name
 820         -> StgBinderInfo
 821         -> LambdaFormInfo
 822         -> Bool
 823 funInfoTableRequired  binder (StgBinderInfo arg_occ unsat_occ _ _ _)
 824                      (LFReEntrant _ top_level _ _)
 825   = (case top_level of { NotTopLevel -> True; TopLevel -> False })
 826     || arg_occ          -- There's an argument occurrence
 827     || unsat_occ        -- There's an unsaturated call
 828     || isExternallyVisibleName binder
 829
 830 funInfoTableRequired other_binder_info binder other_lf_info = True
 831 \end{code}
 832
 833 %************************************************************************
 834 %*                                                                      *
 835 \subsection[ClosureInfo-misc-funs]{Misc functions about @ClosureInfo@, etc.}
 836 %*                                                                      *
 837 %************************************************************************
 838
 839 \begin{code}
 840
 841 isStaticClosure :: ClosureInfo -> Bool
 842 isStaticClosure  (MkClosureInfo _ _ rep) = isStaticRep  rep
 843
 844 closureName :: ClosureInfo -> Name
 845 closureName (MkClosureInfo name _ _) = name
 846
 847 closureSMRep :: ClosureInfo -> SMRep
 848 closureSMRep (MkClosureInfo _ _ sm_rep) = sm_rep
 849
 850 closureLFInfo :: ClosureInfo -> LambdaFormInfo
 851 closureLFInfo (MkClosureInfo _ lf_info _) = lf_info
 852
 853 closureUpdReqd :: ClosureInfo -> Bool
 854
 855 closureUpdReqd (MkClosureInfo _ (LFThunk _ _ _ upd _) _) = upd
 856 closureUpdReqd (MkClosureInfo _ LFBlackHole _)         = True
 857         -- Black-hole closures are allocated to receive the results of an
 858         -- alg case with a named default... so they need to be updated.
 859 closureUpdReqd other_closure                           = False
 860
 861 closureSingleEntry :: ClosureInfo -> Bool
 862
 863 closureSingleEntry (MkClosureInfo _ (LFThunk _ _ _ upd _) _) = not upd
 864 closureSingleEntry other_closure                           = False
 865 \end{code}
 866
 867 \begin{code}
 868 closureSemiTag :: ClosureInfo -> Maybe Int
 869
 870 closureSemiTag (MkClosureInfo _ lf_info _)
 871   = case lf_info of
 872       LFCon data_con _ -> Just (dataConTag data_con - fIRST_TAG)
 873       LFTuple _ _      -> Just 0
 874       _                -> Nothing
 875 \end{code}
 876
 877 \begin{code}
 878 isToplevClosure :: ClosureInfo -> Bool
 879
 880 isToplevClosure (MkClosureInfo _ lf_info _)
 881   = case lf_info of
 882       LFReEntrant _ TopLevel _ _ -> True
 883       LFThunk _ TopLevel _ _ _   -> True
 884       other -> False
 885 \end{code}
 886
 887 \begin{code}
 888 isLetNoEscape :: ClosureInfo -> Bool
 889
 890 isLetNoEscape (MkClosureInfo _ (LFLetNoEscape _) _) = True
 891 isLetNoEscape _ = False
 892 \end{code}
 893
 894 Label generation.
 895
 896 \begin{code}
 897 fastLabelFromCI :: ClosureInfo -> CLabel
 898 fastLabelFromCI (MkClosureInfo name (LFReEntrant _ _ arity _) _)
 899   = mkFastEntryLabel name arity
 900
 901 fastLabelFromCI (MkClosureInfo name _ _)
 902   = pprPanic "fastLabelFromCI" (ppr name)
 903
 904 infoTableLabelFromCI :: ClosureInfo -> CLabel
 905 infoTableLabelFromCI (MkClosureInfo id lf_info rep)
 906   = case lf_info of
 907         LFCon con _     -> mkConInfoPtr con rep
 908         LFTuple tup _   -> mkConInfoPtr tup rep
 909
 910         LFBlackHole     -> mkBlackHoleInfoTableLabel
 911
 912         LFThunk _ _ _ upd_flag (SelectorThunk offset) ->
 913                 mkSelectorInfoLabel upd_flag offset
 914
 915         LFThunk _ _ _ upd_flag (ApThunk arity) ->
 916                 mkApInfoTableLabel upd_flag arity
 917
 918         other -> {-NO: if isStaticRep rep
 919                  then mkStaticInfoTableLabel id
 920                  else -} mkInfoTableLabel id
 921
 922 mkConInfoPtr :: DataCon -> SMRep -> CLabel
 923 mkConInfoPtr con rep
 924   = case rep of
 925       StaticRep _ _ _ -> mkStaticInfoTableLabel  name
 926       _               -> mkConInfoTableLabel     name
 927   where
 928     name = dataConName con
 929
 930 mkConEntryPtr :: DataCon -> SMRep -> CLabel
 931 mkConEntryPtr con rep
 932   = case rep of
 933       StaticRep _ _ _ -> mkStaticConEntryLabel (dataConName con)
 934       _               -> mkConEntryLabel       (dataConName con)
 935   where
 936     name = dataConName con
 937
 938 closureLabelFromCI (MkClosureInfo name _ rep)
 939         | isConstantRep rep
 940         = mkStaticClosureLabel name
 941         -- This case catches those pesky static closures for nullary constructors
 942
 943 closureLabelFromCI (MkClosureInfo id _ other_rep)   = mkClosureLabel id
 944
 945 entryLabelFromCI :: ClosureInfo -> CLabel
 946 entryLabelFromCI (MkClosureInfo id lf_info rep)
 947   = case lf_info of
 948         LFThunk _ _ _ upd_flag std_form_info -> thunkEntryLabel id std_form_info upd_flag
 949         LFCon con _                          -> mkConEntryPtr con rep
 950         LFTuple tup _                        -> mkConEntryPtr tup rep
 951         other                                -> mkStdEntryLabel id
 952
 953 -- thunkEntryLabel is a local help function, not exported.  It's used from both
 954 -- entryLabelFromCI and getEntryConvention.
 955
 956 thunkEntryLabel thunk_id (ApThunk arity) is_updatable
 957   = mkApEntryLabel is_updatable arity
 958 thunkEntryLabel thunk_id (SelectorThunk offset) upd_flag
 959   = mkSelectorEntryLabel upd_flag offset
 960 thunkEntryLabel thunk_id _ is_updatable
 961   = mkStdEntryLabel thunk_id
 962 \end{code}
 963
 964 \begin{code}
 965 allocProfilingMsg :: ClosureInfo -> FAST_STRING
 966
 967 allocProfilingMsg (MkClosureInfo _ lf_info _)
 968   = case lf_info of
 969       LFReEntrant _ _ _ _       -> SLIT("TICK_ALLOC_FUN")
 970       LFCon _ _                 -> SLIT("TICK_ALLOC_CON")
 971       LFTuple _ _               -> SLIT("TICK_ALLOC_CON")
 972       LFThunk _ _ _ _ _         -> SLIT("TICK_ALLOC_THK")
 973       LFBlackHole               -> SLIT("TICK_ALLOC_BH")
 974       LFImported                -> panic "TICK_ALLOC_IMP"
 975 \end{code}
 976
 977 We need a black-hole closure info to pass to @allocDynClosure@ when we
 978 want to allocate the black hole on entry to a CAF.
 979
 980 \begin{code}
 981 blackHoleClosureInfo (MkClosureInfo name _ _)
 982   = MkClosureInfo name LFBlackHole BlackHoleRep
 983 \end{code}
 984
 985 %************************************************************************
 986 %*                                                                      *
 987 \subsection[ClosureInfo-Profiling-funs]{Misc functions about for profiling info.}
 988 %*                                                                      *
 989 %************************************************************************
 990
 991 Profiling requires two pieces of information to be determined for
 992 each closure's info table --- description and type.
 993
 994 The description is stored directly in the @CClosureInfoTable@ when the
 995 info table is built.
 996
 997 The type is determined from the type information stored with the @Id@
 998 in the closure info using @closureTypeDescr@.
 999
1000 \begin{code}
1001 closureTypeDescr :: ClosureInfo -> String
1002 closureTypeDescr (MkClosureInfo name (LFThunk ty _ _ _ _) _)
1003   = getTyDescription ty
1004 closureTypeDescr (MkClosureInfo name (LFReEntrant ty _ _ _) _)
1005   = getTyDescription ty
1006 closureTypeDescr (MkClosureInfo name lf _)
1007   = showSDoc (ppr name)
1008 \end{code}
1009