PrimOps.hs 27.3 KB
Newer Older
Austin Seipp's avatar
Austin Seipp committed
1 2 3
{-
(c) The GRASP/AQUA Project, Glasgow University, 1992-1998

4
\section[PrimOp]{Primitive operations (machine-level)}
Austin Seipp's avatar
Austin Seipp committed
5
-}
6

7 8
{-# LANGUAGE CPP #-}

Sylvain Henry's avatar
Sylvain Henry committed
9
module GHC.Builtin.PrimOps (
10
        PrimOp(..), PrimOpVecCat(..), allThePrimOps,
Sylvain Henry's avatar
Sylvain Henry committed
11
        primOpType, primOpSig, primOpResultType,
12
        primOpTag, maxPrimOpTag, primOpOcc,
13
        primOpWrapperId,
14

15
        tagToEnumKey,
16

17
        primOpOutOfLine, primOpCodeSize,
18
        primOpOkForSpeculation, primOpOkForSideEffects,
mniip's avatar
mniip committed
19
        primOpIsCheap, primOpFixity, primOpDocs,
20

21
        getPrimOpResultInfo,  isComparisonPrimOp, PrimOpResultInfo(..),
22 23

        PrimCall(..)
24 25 26 27
    ) where

#include "HsVersions.h"

28
import GHC.Prelude
29

Sylvain Henry's avatar
Sylvain Henry committed
30 31
import GHC.Builtin.Types.Prim
import GHC.Builtin.Types
32

33
import GHC.Cmm.Type
Sylvain Henry's avatar
Sylvain Henry committed
34 35 36 37
import GHC.Types.Demand
import GHC.Types.Id      ( Id, mkVanillaGlobalWithInfo )
import GHC.Types.Id.Info ( vanillaIdInfo, setCafInfo, CafInfo(NoCafRefs) )
import GHC.Types.Name
Sylvain Henry's avatar
Sylvain Henry committed
38
import GHC.Builtin.Names ( gHC_PRIMOPWRAPPERS )
Sylvain Henry's avatar
Sylvain Henry committed
39 40
import GHC.Core.TyCon    ( TyCon, isPrimTyCon, PrimRep(..) )
import GHC.Core.Type
41
import GHC.Types.RepType ( tyConPrimRep1 )
Sylvain Henry's avatar
Sylvain Henry committed
42 43 44 45
import GHC.Types.Basic   ( Arity, Fixity(..), FixityDirection(..), Boxity(..),
                           SourceText(..) )
import GHC.Types.SrcLoc  ( wiredInSrcSpan )
import GHC.Types.ForeignCall ( CLabelString )
Aditya Gupta's avatar
Aditya Gupta committed
46 47
import GHC.Types.Unique  ( Unique)
import GHC.Builtin.Uniques (mkPrimOpIdUnique, mkPrimOpWrapperUnique )
48
import GHC.Unit.Types    ( Unit )
49 50
import GHC.Utils.Outputable
import GHC.Data.FastString
51

Austin Seipp's avatar
Austin Seipp committed
52 53 54
{-
************************************************************************
*                                                                      *
55
\subsection[PrimOp-datatype]{Datatype for @PrimOp@ (an enumeration)}
Austin Seipp's avatar
Austin Seipp committed
56 57
*                                                                      *
************************************************************************
58 59

These are in \tr{state-interface.verb} order.
Austin Seipp's avatar
Austin Seipp committed
60
-}
61

62
-- supplies:
63
-- data PrimOp = ...
64
#include "primop-data-decl.hs-incl"
65

66
-- supplies
67
-- primOpTag :: PrimOp -> Int
68
#include "primop-tag.hs-incl"
69
primOpTag _ = error "primOpTag: unknown primop"
70

71

72
instance Eq PrimOp where
73
    op1 == op2 = primOpTag op1 == primOpTag op2
74 75

instance Ord PrimOp where
76 77 78 79
    op1 <  op2 =  primOpTag op1 < primOpTag op2
    op1 <= op2 =  primOpTag op1 <= primOpTag op2
    op1 >= op2 =  primOpTag op1 >= primOpTag op2
    op1 >  op2 =  primOpTag op1 > primOpTag op2
80
    op1 `compare` op2 | op1 < op2  = LT
81 82
                      | op1 == op2 = EQ
                      | otherwise  = GT
83 84 85 86

instance Outputable PrimOp where
    ppr op = pprPrimOp op

87 88 89 90
data PrimOpVecCat = IntVec
                  | WordVec
                  | FloatVec

Austin Seipp's avatar
Austin Seipp committed
91
-- An @Enum@-derived list would be better; meanwhile... (ToDo)
92

93 94
allThePrimOps :: [PrimOp]
allThePrimOps =
95
#include "primop-list.hs-incl"
96

97 98 99
tagToEnumKey :: Unique
tagToEnumKey = mkPrimOpIdUnique (primOpTag TagToEnumOp)

Austin Seipp's avatar
Austin Seipp committed
100 101 102
{-
************************************************************************
*                                                                      *
103
\subsection[PrimOp-info]{The essential info about each @PrimOp@}
Austin Seipp's avatar
Austin Seipp committed
104 105 106 107
*                                                                      *
************************************************************************
-}

108
data PrimOpInfo
109
  = Compare     OccName         -- string :: T -> T -> Int#
110 111 112 113 114
                Type
  | GenPrimOp   OccName         -- string :: \/a1..an . T1 -> .. -> Tk -> T
                [TyVar]
                [Type]
                Type
115

116
mkCompare :: FastString -> Type -> PrimOpInfo
117
mkCompare str ty = Compare (mkVarOccFS str) ty
118 119

mkGenPrimOp :: FastString -> [TyVar] -> [Type] -> Type -> PrimOpInfo
120
mkGenPrimOp str tvs tys ty = GenPrimOp (mkVarOccFS str) tvs tys ty
121

Austin Seipp's avatar
Austin Seipp committed
122 123 124
{-
************************************************************************
*                                                                      *
125
\subsubsection{Strictness}
Austin Seipp's avatar
Austin Seipp committed
126 127
*                                                                      *
************************************************************************
128 129

Not all primops are strict!
Austin Seipp's avatar
Austin Seipp committed
130
-}
131

132
primOpStrictness :: PrimOp -> Arity -> StrictSig
133 134 135
        -- See Demand.StrictnessInfo for discussion of what the results
        -- The arity should be the arity of the primop; that's why
        -- this function isn't exported.
136
#include "primop-strictness.hs-incl"
137

Austin Seipp's avatar
Austin Seipp committed
138 139 140
{-
************************************************************************
*                                                                      *
141
\subsubsection{Fixity}
Austin Seipp's avatar
Austin Seipp committed
142 143 144
*                                                                      *
************************************************************************
-}
145 146 147 148

primOpFixity :: PrimOp -> Maybe Fixity
#include "primop-fixity.hs-incl"

mniip's avatar
mniip committed
149 150 151 152 153 154
{-
************************************************************************
*                                                                      *
\subsubsection{Docs}
*                                                                      *
************************************************************************
155

mniip's avatar
mniip committed
156
See Note [GHC.Prim Docs]
mniip's avatar
mniip committed
157 158
-}

159
primOpDocs :: [(String, String)]
mniip's avatar
mniip committed
160 161
#include "primop-docs.hs-incl"

Austin Seipp's avatar
Austin Seipp committed
162 163 164
{-
************************************************************************
*                                                                      *
165
\subsubsection[PrimOp-comparison]{PrimOpInfo basic comparison ops}
Austin Seipp's avatar
Austin Seipp committed
166 167
*                                                                      *
************************************************************************
168 169 170

@primOpInfo@ gives all essential information (from which everything
else, notably a type, can be constructed) for each @PrimOp@.
Austin Seipp's avatar
Austin Seipp committed
171
-}
172 173

primOpInfo :: PrimOp -> PrimOpInfo
174
#include "primop-primop-info.hs-incl"
175
primOpInfo _ = error "primOpInfo: unknown primop"
176

Austin Seipp's avatar
Austin Seipp committed
177
{-
178
Here are a load of comments from the old primOp info:
179 180 181 182 183 184 185 186

A @Word#@ is an unsigned @Int#@.

@decodeFloat#@ is given w/ Integer-stuff (it's similar).

@decodeDouble#@ is given w/ Integer-stuff (it's similar).

Decoding of floating-point numbers is sorta Integer-related.  Encoding
187
is done with plain ccalls now (see PrelNumExtra.hs).
188 189 190

A @Weak@ Pointer is created by the @mkWeak#@ primitive:

191 192
        mkWeak# :: k -> v -> f -> State# RealWorld
                        -> (# State# RealWorld, Weak# v #)
193 194 195

In practice, you'll use the higher-level

196 197
        data Weak v = Weak# v
        mkWeak :: k -> v -> IO () -> IO (Weak v)
198 199 200 201 202

The following operation dereferences a weak pointer.  The weak pointer
may have been finalized, so the operation returns a result code which
must be inspected before looking at the dereferenced value.

203 204
        deRefWeak# :: Weak# v -> State# RealWorld ->
                        (# State# RealWorld, v, Int# #)
205 206 207 208 209

Only look at v if the Int# returned is /= 0 !!

The higher-level op is

210
        deRefWeak :: Weak v -> IO (Maybe v)
211 212

Weak pointers can be finalized early by using the finalize# operation:
213 214 215

        finalizeWeak# :: Weak# v -> State# RealWorld ->
                           (# State# RealWorld, Int#, IO () #)
216 217 218

The Int# returned is either

219 220
        0 if the weak pointer has already been finalized, or it has no
          finalizer (the third component is then invalid).
221

222 223
        1 if the weak pointer is still alive, with the finalizer returned
          as the third component.
224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260

A {\em stable name/pointer} is an index into a table of stable name
entries.  Since the garbage collector is told about stable pointers,
it is safe to pass a stable pointer to external systems such as C
routines.

\begin{verbatim}
makeStablePtr#  :: a -> State# RealWorld -> (# State# RealWorld, StablePtr# a #)
freeStablePtr   :: StablePtr# a -> State# RealWorld -> State# RealWorld
deRefStablePtr# :: StablePtr# a -> State# RealWorld -> (# State# RealWorld, a #)
eqStablePtr#    :: StablePtr# a -> StablePtr# a -> Int#
\end{verbatim}

It may seem a bit surprising that @makeStablePtr#@ is a @IO@
operation since it doesn't (directly) involve IO operations.  The
reason is that if some optimisation pass decided to duplicate calls to
@makeStablePtr#@ and we only pass one of the stable pointers over, a
massive space leak can result.  Putting it into the IO monad
prevents this.  (Another reason for putting them in a monad is to
ensure correct sequencing wrt the side-effecting @freeStablePtr@
operation.)

An important property of stable pointers is that if you call
makeStablePtr# twice on the same object you get the same stable
pointer back.

Note that we can implement @freeStablePtr#@ using @_ccall_@ (and,
besides, it's not likely to be used from Haskell) so it's not a
primop.

Question: Why @RealWorld@ - won't any instance of @_ST@ do the job? [ADR]

Stable Names
~~~~~~~~~~~~

A stable name is like a stable pointer, but with three important differences:

261 262 263
        (a) You can't deRef one to get back to the original object.
        (b) You can convert one to an Int.
        (c) You don't need to 'freeStableName'
264 265 266 267 268 269

The existence of a stable name doesn't guarantee to keep the object it
points to alive (unlike a stable pointer), hence (a).

Invariants:

270 271 272 273 274
        (a) makeStableName always returns the same value for a given
            object (same as stable pointers).

        (b) if two stable names are equal, it implies that the objects
            from which they were created were the same.
275

276 277
        (c) stableNameToInt always returns the same Int for a given
            stable name.
278 279


Krzysztof Gogolewski's avatar
Typos  
Krzysztof Gogolewski committed
280
These primops are pretty weird.
281

282
        tagToEnum# :: Int -> a    (result type must be an enumerated type)
283 284 285 286

The constraints aren't currently checked by the front end, but the
code generator will fall over if they aren't satisfied.

Austin Seipp's avatar
Austin Seipp committed
287 288
************************************************************************
*                                                                      *
289
            Which PrimOps are out-of-line
Austin Seipp's avatar
Austin Seipp committed
290 291
*                                                                      *
************************************************************************
292 293 294

Some PrimOps need to be called out-of-line because they either need to
perform a heap check or they block.
Austin Seipp's avatar
Austin Seipp committed
295
-}
296

apt's avatar
apt committed
297
primOpOutOfLine :: PrimOp -> Bool
298
#include "primop-out-of-line.hs-incl"
299

Austin Seipp's avatar
Austin Seipp committed
300 301 302
{-
************************************************************************
*                                                                      *
303
            Failure and side effects
Austin Seipp's avatar
Austin Seipp committed
304 305
*                                                                      *
************************************************************************
306

307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323
Note [Checking versus non-checking primops]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  In GHC primops break down into two classes:

   a. Checking primops behave, for instance, like division. In this
      case the primop may throw an exception (e.g. division-by-zero)
      and is consequently is marked with the can_fail flag described below.
      The ability to fail comes at the expense of precluding some optimizations.

   b. Non-checking primops behavior, for instance, like addition. While
      addition can overflow it does not produce an exception. So can_fail is
      set to False, and we get more optimisation opportunities.  But we must
      never throw an exception, so we cannot rewrite to a call to error.

  It is important that a non-checking primop never be transformed in a way that
  would cause it to bottom. Doing so would violate Core's let/app invariant
Sylvain Henry's avatar
Sylvain Henry committed
324
  (see Note [Core let/app invariant] in GHC.Core) which is critical to
325 326 327
  the simplifier's ability to float without fear of changing program meaning.


328 329
Note [PrimOp can_fail and has_side_effects]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
330 331 332
Both can_fail and has_side_effects mean that the primop has
some effect that is not captured entirely by its result value.

333 334 335 336 337 338 339 340 341 342 343 344 345 346
----------  has_side_effects ---------------------
A primop "has_side_effects" if it has some *write* effect, visible
elsewhere
    - writing to the world (I/O)
    - writing to a mutable data structure (writeIORef)
    - throwing a synchronous Haskell exception

Often such primops have a type like
   State -> input -> (State, output)
so the state token guarantees ordering.  In general we rely *only* on
data dependencies of the state token to enforce write-effect ordering

 * NB1: if you inline unsafePerformIO, you may end up with
   side-effecting ops whose 'state' output is discarded.
347
   And programmers may do that by hand; see #9390.
348 349 350 351 352 353 354 355 356 357
   That is why we (conservatively) do not discard write-effecting
   primops even if both their state and result is discarded.

 * NB2: We consider primops, such as raiseIO#, that can raise a
   (Haskell) synchronous exception to "have_side_effects" but not
   "can_fail".  We must be careful about not discarding such things;
   see the paper "A semantics for imprecise exceptions".

 * NB3: *Read* effects (like reading an IORef) don't count here,
   because it doesn't matter if we don't do them, or do them more than
358
   once.  *Sequencing* is maintained by the data dependency of the state
359 360 361
   token.

----------  can_fail ----------------------------
362
A primop "can_fail" if it can fail with an *unchecked* exception on
363
some elements of its input domain. Main examples:
364
   division (fails on zero denominator)
365 366
   array indexing (fails if the index is out of bounds)

367 368
An "unchecked exception" is one that is an outright error, (not
turned into a Haskell exception,) such as seg-fault or
369 370
divide-by-zero error.  Such can_fail primops are ALWAYS surrounded
with a test that checks for the bad cases, but we need to be
371
very careful about code motion that might move it out of
372 373 374 375 376 377 378 379
the scope of the test.

Note [Transformations affected by can_fail and has_side_effects]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The can_fail and has_side_effects properties have the following effect
on program transformations.  Summary table is followed by details.

            can_fail     has_side_effects
380
Discard        YES           NO
381 382 383 384 385 386 387 388 389 390
Float in       YES           YES
Float out      NO            NO
Duplicate      YES           NO

* Discarding.   case (a `op` b) of _ -> rhs  ===>   rhs
  You should not discard a has_side_effects primop; e.g.
     case (writeIntArray# a i v s of (# _, _ #) -> True
  Arguably you should be able to discard this, since the
  returned stat token is not used, but that relies on NEVER
  inlining unsafePerformIO, and programmers sometimes write
391
  this kind of stuff by hand (#9390).  So we (conservatively)
392 393 394 395 396
  never discard a has_side_effects primop.

  However, it's fine to discard a can_fail primop.  For example
     case (indexIntArray# a i) of _ -> True
  We can discard indexIntArray#; it has can_fail, but not
397
  has_side_effects; see #5658 which was all about this.
398 399 400 401 402 403 404 405 406 407
  Notice that indexIntArray# is (in a more general handling of
  effects) read effect, but we don't care about that here, and
  treat read effects as *not* has_side_effects.

  Similarly (a `/#` b) can be discarded.  It can seg-fault or
  cause a hardware exception, but not a synchronous Haskell
  exception.



408
  Synchronous Haskell exceptions, e.g. from raiseIO#, are treated
409 410 411 412 413 414 415
  as has_side_effects and hence are not discarded.

* Float in.  You can float a can_fail or has_side_effects primop
  *inwards*, but not inside a lambda (see Duplication below).

* Float out.  You must not float a can_fail primop *outwards* lest
  you escape the dynamic scope of the test.  Example:
416 417 418 419 420 421 422 423 424
      case d ># 0# of
        True  -> case x /# d of r -> r +# 1
        False -> 0
  Here we must not float the case outwards to give
      case x/# d of r ->
      case d ># 0# of
        True  -> r +# 1
        False -> 0

425 426
  Nor can you float out a has_side_effects primop.  For example:
       if blah then case writeMutVar# v True s0 of (# s1 #) -> s1
427
               else s0
428
  Notice that s0 is mentioned in both branches of the 'if', but
429 430
  only one of these two will actually be consumed.  But if we
  float out to
431 432
      case writeMutVar# v True s0 of (# s1 #) ->
      if blah then s1 else s0
433 434 435
  the writeMutVar will be performed in both branches, which is
  utterly wrong.

436 437 438 439
* Duplication.  You cannot duplicate a has_side_effect primop.  You
  might wonder how this can occur given the state token threading, but
  just look at Control.Monad.ST.Lazy.Imp.strictToLazy!  We get
  something like this
440
        p = case readMutVar# s v of
Sylvain Henry's avatar
Sylvain Henry committed
441
              (# s', r #) -> (State# s', r)
442 443 444 445 446
        s' = case p of (s', r) -> s'
        r  = case p of (s', r) -> r

  (All these bindings are boxed.)  If we inline p at its two call
  sites, we get a catastrophe: because the read is performed once when
447
  s' is demanded, and once when 'r' is demanded, which may be much
448
  later.  Utterly wrong.  #3207 is real example of this happening.
449

450 451
  However, it's fine to duplicate a can_fail primop.  That is really
  the only difference between can_fail and has_side_effects.
452

453
Note [Implementation: how can_fail/has_side_effects affect transformations]
454
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
455
How do we ensure that floating/duplication/discarding are done right
456
in the simplifier?
457

458 459 460
Two main predicates on primpops test these flags:
  primOpOkForSideEffects <=> not has_side_effects
  primOpOkForSpeculation <=> not (has_side_effects || can_fail)
461

462 463 464
  * The "no-float-out" thing is achieved by ensuring that we never
    let-bind a can_fail or has_side_effects primop.  The RHS of a
    let-binding (which can float in and out freely) satisfies
465 466
    exprOkForSpeculation; this is the let/app invariant.  And
    exprOkForSpeculation is false of can_fail and has_side_effects.
467

468
  * So can_fail and has_side_effects primops will appear only as the
469 470
    scrutinees of cases, and that's why the FloatIn pass is capable
    of floating case bindings inwards.
471

472 473
  * The no-duplicate thing is done via primOpIsCheap, by making
    has_side_effects things (very very very) not-cheap!
Austin Seipp's avatar
Austin Seipp committed
474
-}
475 476 477 478 479 480 481

primOpHasSideEffects :: PrimOp -> Bool
#include "primop-has-side-effects.hs-incl"

primOpCanFail :: PrimOp -> Bool
#include "primop-can-fail.hs-incl"

482
primOpOkForSpeculation :: PrimOp -> Bool
483
  -- See Note [PrimOp can_fail and has_side_effects]
Sylvain Henry's avatar
Sylvain Henry committed
484
  -- See comments with GHC.Core.Utils.exprOkForSpeculation
485
  -- primOpOkForSpeculation => primOpOkForSideEffects
486
primOpOkForSpeculation op
487 488 489
  =  primOpOkForSideEffects op
  && not (primOpOutOfLine op || primOpCanFail op)
    -- I think the "out of line" test is because out of line things can
490
    -- be expensive (eg sine, cosine), and so we may not want to speculate them
491 492 493 494

primOpOkForSideEffects :: PrimOp -> Bool
primOpOkForSideEffects op
  = not (primOpHasSideEffects op)
495

Austin Seipp's avatar
Austin Seipp committed
496
{-
497 498
Note [primOpIsCheap]
~~~~~~~~~~~~~~~~~~~~
499

Sylvain Henry's avatar
Sylvain Henry committed
500
@primOpIsCheap@, as used in GHC.Core.Opt.Simplify.Utils.  For now (HACK
501 502 503 504
WARNING), we just borrow some other predicates for a
what-should-be-good-enough test.  "Cheap" means willing to call it more
than once, and/or push it inside a lambda.  The latter could change the
behaviour of 'seq' for primops that can fail, so we don't treat them as cheap.
Austin Seipp's avatar
Austin Seipp committed
505
-}
506 507

primOpIsCheap :: PrimOp -> Bool
508
-- See Note [PrimOp can_fail and has_side_effects]
509
primOpIsCheap op = primOpOkForSpeculation op
510 511
-- In March 2001, we changed this to
--      primOpIsCheap op = False
512
-- thereby making *no* primops seem cheap.  But this killed eta
513
-- expansion on case (x ==# y) of True -> \s -> ...
514
-- which is bad.  In particular a loop like
515
--      doLoop n = loop 0
516 517 518 519
--     where
--         loop i | i == n    = return ()
--                | otherwise = bar i >> loop (i+1)
-- allocated a closure every time round because it doesn't eta expand.
520
--
521
-- The problem that originally gave rise to the change was
522
--      let x = a +# b *# c in x +# x
523 524 525
-- were we don't want to inline x. But primopIsCheap doesn't control
-- that (it's exprIsDupable that does) so the problem doesn't occur
-- even if primOpIsCheap sometimes says 'True'.
526

Austin Seipp's avatar
Austin Seipp committed
527 528 529
{-
************************************************************************
*                                                                      *
530
               PrimOp code size
Austin Seipp's avatar
Austin Seipp committed
531 532
*                                                                      *
************************************************************************
533

534 535 536
primOpCodeSize
~~~~~~~~~~~~~~
Gives an indication of the code size of a primop, for the purposes of
Sylvain Henry's avatar
Sylvain Henry committed
537
calculating unfolding sizes; see GHC.Core.Unfold.sizeExpr.
Austin Seipp's avatar
Austin Seipp committed
538
-}
539

540 541 542 543 544
primOpCodeSize :: PrimOp -> Int
#include "primop-code-size.hs-incl"

primOpCodeSizeDefault :: Int
primOpCodeSizeDefault = 1
Sylvain Henry's avatar
Sylvain Henry committed
545
  -- GHC.Core.Unfold.primOpSize already takes into account primOpOutOfLine
546
  -- and adds some further costs for the args in that case.
547

548 549
primOpCodeSizeForeignCall :: Int
primOpCodeSizeForeignCall = 4
550

Austin Seipp's avatar
Austin Seipp committed
551 552 553
{-
************************************************************************
*                                                                      *
554
               PrimOp types
Austin Seipp's avatar
Austin Seipp committed
555 556 557
*                                                                      *
************************************************************************
-}
558 559 560

primOpType :: PrimOp -> Type  -- you may want to use primOpSig instead
primOpType op
Ian Lynagh's avatar
Ian Lynagh committed
561 562
  = case primOpInfo op of
    Compare _occ ty -> compare_fun_ty ty
563

564
    GenPrimOp _occ tyvars arg_tys res_ty ->
Krzysztof Gogolewski's avatar
Krzysztof Gogolewski committed
565
        mkSpecForAllTys tyvars (mkVisFunTysMany arg_tys res_ty)
566

Sylvain Henry's avatar
Sylvain Henry committed
567 568 569 570 571 572
primOpResultType :: PrimOp -> Type
primOpResultType op
  = case primOpInfo op of
    Compare _occ _ty -> intPrimTy
    GenPrimOp _occ _tyvars _arg_tys res_ty -> res_ty

573
primOpOcc :: PrimOp -> OccName
Ian Lynagh's avatar
Ian Lynagh committed
574 575 576
primOpOcc op = case primOpInfo op of
               Compare   occ _     -> occ
               GenPrimOp occ _ _ _ -> occ
577

578 579
{- Note [Primop wrappers]
~~~~~~~~~~~~~~~~~~~~~~~~~
Ben Gamari's avatar
Ben Gamari committed
580 581 582 583 584 585

To support (limited) use of primops in GHCi genprimopcode generates the
GHC.PrimopWrappers module. This module contains a "primop wrapper"
binding for each primop. These are standard Haskell functions mirroring the
types of the primops they wrap. For instance, in the case of plusInt# we would
have:
586 587 588

    module GHC.PrimopWrappers where
    import GHC.Prim as P
Ben Gamari's avatar
Ben Gamari committed
589 590

    plusInt# :: Int# -> Int# -> Int#
591 592
    plusInt# a b = P.plusInt# a b

Ben Gamari's avatar
Ben Gamari committed
593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650
The Id for the wrapper of a primop can be found using
'GHC.Builtin.PrimOp.primOpWrapperId'. However, GHCi does not use this mechanism
to link primops; it rather does a rather hacky symbol lookup (see
GHC.ByteCode.Linker.primopToCLabel). TODO: Perhaps this should be changed?

Note that these wrappers aren't *quite*
as expressive as their unwrapped breathern in that they may exhibit less levity
polymorphism. For instance, consider the case of mkWeakNoFinalizer# which has
type:

    mkWeakNoFinalizer# :: forall (r :: RuntimeRep) (k :: TYPE r) (v :: Type).
                          k -> v
                       -> State# RealWorld
                       -> (# State# RealWorld, Weak# v #)

Naively we could generate a wrapper of the form,


    mkWeakNoFinalizer# k v s = GHC.Prim.mkWeakNoFinalizer# k v s

However, this would require that 'k' bind the levity-polymorphic key,
which is disallowed by our levity polymorphism validity checks (see Note
[Levity polymorphism invariants] in GHC.Core). Consequently, we give the
wrapper the simpler, less polymorphic type

    mkWeakNoFinalizer# :: forall (k :: Type) (v :: Type).
                          k -> v
                       -> State# RealWorld
                       -> (# State# RealWorld, Weak# v #)

This simplification tends to be good enough for GHCi uses given that there are
few levity polymorphic primops and we do little simplification on interpreted
code anyways.

TODO: This behavior is actually wrong; a program becomes ill-typed upon
replacing a real primop occurrence with one of its wrapper due to the fact that
the former has an additional type binder. Hmmm....

Note [Eta expanding primops]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

STG requires that primop applications be saturated. This makes code generation
significantly simpler since otherwise we would need to define a calling
convention for curried applications that can accomodate levity polymorphism.

To ensure saturation, CorePrep eta expands expand all primop applications as
described in Note [Eta expansion of hasNoBinding things in CorePrep] in
GHC.Core.Prep.

Historical Note:

For a short period around GHC 8.8 we rewrote unsaturated primop applications to
rather use the primop's wrapper (see Note [Primop wrappers] in
GHC.Builtin.PrimOps) instead of eta expansion. This was because at the time
CoreTidy would try to predict the CAFfyness of bindings that would be produced
by CorePrep for inclusion in interface files. Eta expanding during CorePrep
proved to be very difficult to predict, leading to nasty inconsistencies in
CAFfyness determinations (see #16846).
651

Ben Gamari's avatar
Ben Gamari committed
652 653 654 655 656
Thankfully, we now no longer try to predict CAFfyness but rather compute it on
GHC STG (see Note [SRTs] in GHC.Cmm.Info.Build) and inject it into the interface
file after code generation (see TODO: Refer to whatever falls out of #18096).
This is much simpler and avoids the potential for inconsistency, allowing us to
return to the somewhat simpler eta expansion approach for unsaturated primops.
657

Ben Gamari's avatar
Ben Gamari committed
658
See #18079.
659 660 661 662 663 664 665 666 667 668 669 670
-}

-- | Returns the 'Id' of the wrapper associated with the given 'PrimOp'.
-- See Note [Primop wrappers].
primOpWrapperId :: PrimOp -> Id
primOpWrapperId op = mkVanillaGlobalWithInfo name ty info
  where
    info = setCafInfo vanillaIdInfo NoCafRefs
    name = mkExternalName uniq gHC_PRIMOPWRAPPERS (primOpOcc op) wiredInSrcSpan
    uniq = mkPrimOpWrapperUnique (primOpTag op)
    ty   = primOpType op

671 672
isComparisonPrimOp :: PrimOp -> Bool
isComparisonPrimOp op = case primOpInfo op of
673 674
                          Compare {}   -> True
                          GenPrimOp {} -> False
675

676 677
-- primOpSig is like primOpType but gives the result split apart:
-- (type variables, argument types, result type)
678
-- It also gives arity, strictness info
679

680
primOpSig :: PrimOp -> ([TyVar], [Type], Type, Arity, StrictSig)
681
primOpSig op
682
  = (tyvars, arg_tys, res_ty, arity, primOpStrictness op arity)
683 684 685 686
  where
    arity = length arg_tys
    (tyvars, arg_tys, res_ty)
      = case (primOpInfo op) of
687 688
        Compare   _occ ty                    -> ([],     [ty,ty], intPrimTy)
        GenPrimOp _occ tyvars arg_tys res_ty -> (tyvars, arg_tys, res_ty   )
689 690

data PrimOpResultInfo
691 692
  = ReturnsPrim     PrimRep
  | ReturnsAlg      TyCon
693 694 695 696 697 698 699 700

-- Some PrimOps need not return a manifest primitive or algebraic value
-- (i.e. they might return a polymorphic value).  These PrimOps *must*
-- be out of line, or the code generator won't work.

getPrimOpResultInfo :: PrimOp -> PrimOpResultInfo
getPrimOpResultInfo op
  = case (primOpInfo op) of
Richard Eisenberg's avatar
Richard Eisenberg committed
701 702
      Compare _ _                         -> ReturnsPrim (tyConPrimRep1 intPrimTyCon)
      GenPrimOp _ _ _ ty | isPrimTyCon tc -> ReturnsPrim (tyConPrimRep1 tc)
703 704 705 706
                         | otherwise      -> ReturnsAlg tc
                         where
                           tc = tyConAppTyCon ty
                        -- All primops return a tycon-app result
707 708
                        -- The tycon can be an unboxed tuple or sum, though,
                        -- which gives rise to a ReturnAlg
709

Austin Seipp's avatar
Austin Seipp committed
710
{-
711 712 713 714
We do not currently make use of whether primops are commutable.

We used to try to move constants to the right hand side for strength
reduction.
Austin Seipp's avatar
Austin Seipp committed
715
-}
716

717
{-
718
commutableOp :: PrimOp -> Bool
719
#include "primop-commutable.hs-incl"
720
-}
721

Austin Seipp's avatar
Austin Seipp committed
722 723
-- Utils:

724
compare_fun_ty :: Type -> Type
Krzysztof Gogolewski's avatar
Krzysztof Gogolewski committed
725
compare_fun_ty ty = mkVisFunTysMany [ty, ty] intPrimTy
726

Austin Seipp's avatar
Austin Seipp committed
727 728
-- Output stuff:

729
pprPrimOp  :: PrimOp -> SDoc
730
pprPrimOp other_op = pprOccName (primOpOcc other_op)
731

Austin Seipp's avatar
Austin Seipp committed
732 733 734
{-
************************************************************************
*                                                                      *
735
\subsubsection[PrimCall]{User-imported primitive calls}
Austin Seipp's avatar
Austin Seipp committed
736 737 738
*                                                                      *
************************************************************************
-}
739

740
data PrimCall = PrimCall CLabelString Unit
741 742

instance Outputable PrimCall where
743 744
  ppr (PrimCall lbl pkgId)
        = text "__primcall" <+> ppr pkgId <+> ppr lbl