primops.txt.pp 135 KB
Newer Older
1
-----------------------------------------------------------------------
Jan Stolarek's avatar
Jan Stolarek committed
2
--
3
-- (c) 2010 The University of Glasgow
4
--
5
-- Primitive Operations and Types
6
--
7
-- For more information on PrimOps, see
8
--   http://ghc.haskell.org/trac/ghc/wiki/Commentary/PrimOps
9
--
10 11
-----------------------------------------------------------------------

apt's avatar
apt committed
12 13 14 15 16 17
-- This file is processed by the utility program genprimopcode to produce
-- a number of include files within the compiler and optionally to produce
-- human-readable documentation.
--
-- It should first be preprocessed.
--
18 19
-- Information on how PrimOps are implemented and the steps necessary to
-- add a new one can be found in the Commentary:
apt's avatar
apt committed
20
--
21
--  http://ghc.haskell.org/trac/ghc/wiki/Commentary/PrimOps
apt's avatar
apt committed
22

23 24
-- This file is divided into named sections, each containing or more
-- primop entries. Section headers have the format:
apt's avatar
apt committed
25
--
26
--      section "section-name" {description}
apt's avatar
apt committed
27
--
28 29
-- This information is used solely when producing documentation; it is
-- otherwise ignored.  The description is optional.
apt's avatar
apt committed
30 31
--
-- The format of each primop entry is as follows:
32
--
33
--      primop internal-name "name-in-program-text" type category {description} attributes
34

apt's avatar
apt committed
35
-- The default attribute values which apply if you don't specify
36
-- other ones.  Attribute values can be True, False, or arbitrary
Jan Stolarek's avatar
Jan Stolarek committed
37
-- text between curly brackets.  This is a kludge to enable
38 39
-- processors of this file to easily get hold of simple info
-- (eg, out_of_line), whilst avoiding parsing complex expressions
40
-- needed for strictness info.
41 42 43 44 45 46 47 48
--
-- type refers to the general category of the primop. Valid settings include,
--
--  * Compare:   A comparison operation of the shape a -> a -> Int#
--  * Monadic:   A unary operation of shape a -> a
--  * Dyadic:    A binary operation of shape a -> a -> a
--  * GenPrimOp: Any other sort of primop
--
49

50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65
-- The vector attribute is rather special. It takes a list of 3-tuples, each of
-- which is of the form <ELEM_TYPE,SCALAR_TYPE,LENGTH>. ELEM_TYPE is the type of
-- the elements in the vector; LENGTH is the length of the vector; and
-- SCALAR_TYPE is the scalar type used to inject to/project from vector
-- element. Note that ELEM_TYPE and SCALAR_TYPE are not the same; for example,
-- to broadcast a scalar value to a vector whose elements are of type Int8, we
-- use an Int#.

-- When a primtype or primop has a vector attribute, it is instantiated at each
-- 3-tuple in the list of 3-tuples. That is, the vector attribute allows us to
-- define a family of types or primops. Vector support also adds three new
-- keywords: VECTOR, SCALAR, and VECTUPLE. These keywords are expanded to types
-- derived from the 3-tuple. For the 3-tuple <Int64,INT64,2>, VECTOR expands to
-- Int64X2#, SCALAR expands to INT64, and VECTUPLE expands to (# INT64, INT64
-- #).

66 67
defaults
   has_side_effects = False
68 69
   out_of_line      = False   -- See Note Note [PrimOp can_fail and has_side_effects] in PrimOp
   can_fail         = False   -- See Note Note [PrimOp can_fail and has_side_effects] in PrimOp
70
   commutable       = False
71
   code_size        = { primOpCodeSizeDefault }
72
   strictness       = { \ arity -> mkClosedStrictSig (replicate arity topDmd) topRes }
73
   fixity           = Nothing
gmainland's avatar
gmainland committed
74
   llvm_only        = False
75
   vector           = []
76

77 78 79
-- Currently, documentation is produced using latex, so contents of
-- description fields should be legal latex. Descriptions can contain
-- matched pairs of embedded curly brackets.
apt's avatar
apt committed
80 81

#include "MachDeps.h"
82

83 84
-- We need platform defines (tests for mingw32 below).
#include "ghc_boot_platform.h"
apt's avatar
apt committed
85 86

section "The word size story."
87 88 89 90 91 92 93
        {Haskell98 specifies that signed integers (type {\tt Int})
         must contain at least 30 bits. GHC always implements {\tt
         Int} using the primitive type {\tt Int\#}, whose size equals
         the {\tt MachDeps.h} constant {\tt WORD\_SIZE\_IN\_BITS}.
         This is normally set based on the {\tt config.h} parameter
         {\tt SIZEOF\_HSWORD}, i.e., 32 bits on 32-bit machines, 64
         bits on 64-bit machines.  However, it can also be explicitly
94
         set to a smaller number than 64, e.g., 62 bits, to allow the
95
         possibility of using tag bits. Currently GHC itself has only
96
         32-bit and 64-bit variants, but 61, 62, or 63-bit code can be
97
         exported as an external core file for use in other back ends.
98
         30 and 31-bit code is no longer supported.
99 100 101 102 103 104 105 106 107 108

         GHC also implements a primitive unsigned integer type {\tt
         Word\#} which always has the same number of bits as {\tt
         Int\#}.

         In addition, GHC supports families of explicit-sized integers
         and words at 8, 16, 32, and 64 bits, with the usual
         arithmetic operations, comparisons, and a range of
         conversions.  The 8-bit and 16-bit sizes are always
         represented as {\tt Int\#} and {\tt Word\#}, and the
109
         operations implemented in terms of the primops on these
110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137
         types, with suitable range restrictions on the results (using
         the {\tt narrow$n$Int\#} and {\tt narrow$n$Word\#} families
         of primops.  The 32-bit sizes are represented using {\tt
         Int\#} and {\tt Word\#} when {\tt WORD\_SIZE\_IN\_BITS}
         $\geq$ 32; otherwise, these are represented using distinct
         primitive types {\tt Int32\#} and {\tt Word32\#}. These (when
         needed) have a complete set of corresponding operations;
         however, nearly all of these are implemented as external C
         functions rather than as primops.  Exactly the same story
         applies to the 64-bit sizes.  All of these details are hidden
         under the {\tt PrelInt} and {\tt PrelWord} modules, which use
         {\tt \#if}-defs to invoke the appropriate types and
         operators.

         Word size also matters for the families of primops for
         indexing/reading/writing fixed-size quantities at offsets
         from an array base, address, or foreign pointer.  Here, a
         slightly different approach is taken.  The names of these
         primops are fixed, but their {\it types} vary according to
         the value of {\tt WORD\_SIZE\_IN\_BITS}. For example, if word
         size is at least 32 bits then an operator like
         \texttt{indexInt32Array\#} has type {\tt ByteArray\# -> Int\#
         -> Int\#}; otherwise it has type {\tt ByteArray\# -> Int\# ->
         Int32\#}.  This approach confines the necessary {\tt
         \#if}-defs to this file; no conditional compilation is needed
         in the files that expose these primops.

         Finally, there are strongly deprecated primops for coercing
138 139 140 141 142
         between {\tt Addr\#}, the primitive type of machine
         addresses, and {\tt Int\#}.  These are pretty bogus anyway,
         but will work on existing 32-bit and 64-bit GHC targets; they
         are completely bogus when tag bits are used in {\tt Int\#},
         so are not available in this case.  }
apt's avatar
apt committed
143

Jan Stolarek's avatar
Jan Stolarek committed
144 145
-- Define synonyms for indexing ops.

apt's avatar
apt committed
146 147 148 149 150 151 152 153 154 155
#define INT32 Int#
#define WORD32 Word#

#if WORD_SIZE_IN_BITS < 64
#define INT64 Int64#
#define WORD64 Word64#
#else
#define INT64 Int#
#define WORD64 Word#
#endif
156 157

------------------------------------------------------------------------
158
section "Char#"
159
        {Operations on 31-bit characters.}
160 161
------------------------------------------------------------------------

162
primtype Char#
163

164 165
primop   CharGtOp  "gtChar#"   Compare   Char# -> Char# -> Int#
primop   CharGeOp  "geChar#"   Compare   Char# -> Char# -> Int#
166

167
primop   CharEqOp  "eqChar#"   Compare
168
   Char# -> Char# -> Int#
apt's avatar
apt committed
169
   with commutable = True
170

171
primop   CharNeOp  "neChar#"   Compare
172
   Char# -> Char# -> Int#
apt's avatar
apt committed
173 174
   with commutable = True

175 176
primop   CharLtOp  "ltChar#"   Compare   Char# -> Char# -> Int#
primop   CharLeOp  "leChar#"   Compare   Char# -> Char# -> Int#
apt's avatar
apt committed
177 178

primop   OrdOp   "ord#"  GenPrimOp   Char# -> Int#
179
   with code_size = 0
180

181
------------------------------------------------------------------------
apt's avatar
apt committed
182
section "Int#"
183
        {Operations on native-size integers (32+ bits).}
184 185
------------------------------------------------------------------------

186 187
primtype Int#

apt's avatar
apt committed
188 189 190
primop   IntAddOp    "+#"    Dyadic
   Int# -> Int# -> Int#
   with commutable = True
191
        fixity = infixl 6
192

apt's avatar
apt committed
193
primop   IntSubOp    "-#"    Dyadic   Int# -> Int# -> Int#
194
   with fixity = infixl 6
195

Jan Stolarek's avatar
Jan Stolarek committed
196
primop   IntMulOp    "*#"
apt's avatar
apt committed
197
   Dyadic   Int# -> Int# -> Int#
198 199
   {Low word of signed integer multiply.}
   with commutable = True
200
        fixity = infixl 7
201

Jan Stolarek's avatar
Jan Stolarek committed
202
primop   IntMulMayOfloOp  "mulIntMayOflo#"
203 204
   Dyadic   Int# -> Int# -> Int#
   {Return non-zero if there is any possibility that the upper word of a
205
    signed integer multiply might contain useful information.  Return
206
    zero only if you are completely sure that no overflow can occur.
207
    On a 32-bit platform, the recommended implementation is to do a
208
    32 x 32 -> 64 signed multiply, and subtract result[63:32] from
Jan Stolarek's avatar
Jan Stolarek committed
209
    (result[31] >>signed 31).  If this is zero, meaning that the
210 211
    upper word is merely a sign extension of the lower one, no
    overflow can occur.
212

Jan Stolarek's avatar
Jan Stolarek committed
213 214 215 216 217
    On a 64-bit platform it is not always possible to
    acquire the top 64 bits of the result.  Therefore, a recommended
    implementation is to take the absolute value of both operands, and
    return 0 iff bits[63:31] of them are zero, since that means that their
    magnitudes fit within 31 bits, so the magnitude of the product must fit
218 219 220 221
    into 62 bits.

    If in doubt, return non-zero, but do make an effort to create the
    correct answer for small args, since otherwise the performance of
222
    \texttt{(*) :: Integer -> Integer -> Integer} will be poor.
223
   }
apt's avatar
apt committed
224 225 226 227
   with commutable = True

primop   IntQuotOp    "quotInt#"    Dyadic
   Int# -> Int# -> Int#
228 229 230
   {Rounds towards zero. The behavior is undefined if the second argument is
    zero.
   }
apt's avatar
apt committed
231 232 233 234
   with can_fail = True

primop   IntRemOp    "remInt#"    Dyadic
   Int# -> Int# -> Int#
235 236 237
   {Satisfies \texttt{(quotInt\# x y) *\# y +\# (remInt\# x y) == x}. The
    behavior is undefined if the second argument is zero.
   }
apt's avatar
apt committed
238 239
   with can_fail = True

240 241 242 243 244
primop   IntQuotRemOp "quotRemInt#"    GenPrimOp
   Int# -> Int# -> (# Int#, Int# #)
   {Rounds towards zero.}
   with can_fail = True

245 246 247 248 249 250 251 252 253 254 255
primop   AndIOp   "andI#"   Dyadic    Int# -> Int# -> Int#
   with commutable = True

primop   OrIOp   "orI#"     Dyadic    Int# -> Int# -> Int#
   with commutable = True

primop   XorIOp   "xorI#"   Dyadic    Int# -> Int# -> Int#
   with commutable = True

primop   NotIOp   "notI#"   Monadic   Int# -> Int#

apt's avatar
apt committed
256 257
primop   IntNegOp    "negateInt#"    Monadic   Int# -> Int#
primop   IntAddCOp   "addIntC#"    GenPrimOp   Int# -> Int# -> (# Int#, Int# #)
258 259 260 261 262
         {Add signed integers reporting overflow.
          First member of result is the sum truncated to an {\tt Int#};
          second member is zero if the true sum fits in an {\tt Int#},
          nonzero if overflow occurred (the sum is either too large
          or too small to fit in an {\tt Int#}).}
263
   with code_size = 2
Sebastian Graf's avatar
Sebastian Graf committed
264
        commutable = True
265

apt's avatar
apt committed
266
primop   IntSubCOp   "subIntC#"    GenPrimOp   Int# -> Int# -> (# Int#, Int# #)
267 268 269 270 271
         {Subtract signed integers reporting overflow.
          First member of result is the difference truncated to an {\tt Int#};
          second member is zero if the true difference fits in an {\tt Int#},
          nonzero if overflow occurred (the difference is either too large
          or too small to fit in an {\tt Int#}).}
272
   with code_size = 2
273

274
primop   IntGtOp  ">#"   Compare   Int# -> Int# -> Int#
275 276
   with fixity = infix 4

277
primop   IntGeOp  ">=#"   Compare   Int# -> Int# -> Int#
278
   with fixity = infix 4
apt's avatar
apt committed
279

280
primop   IntEqOp  "==#"   Compare
281
   Int# -> Int# -> Int#
apt's avatar
apt committed
282
   with commutable = True
283
        fixity = infix 4
apt's avatar
apt committed
284

285
primop   IntNeOp  "/=#"   Compare
286
   Int# -> Int# -> Int#
apt's avatar
apt committed
287
   with commutable = True
288
        fixity = infix 4
apt's avatar
apt committed
289

290
primop   IntLtOp  "<#"   Compare   Int# -> Int# -> Int#
291 292
   with fixity = infix 4

293
primop   IntLeOp  "<=#"   Compare   Int# -> Int# -> Int#
294
   with fixity = infix 4
apt's avatar
apt committed
295 296

primop   ChrOp   "chr#"   GenPrimOp   Int# -> Char#
297
   with code_size = 0
apt's avatar
apt committed
298 299

primop   Int2WordOp "int2Word#" GenPrimOp Int# -> Word#
300 301
   with code_size = 0

apt's avatar
apt committed
302 303 304
primop   Int2FloatOp   "int2Float#"      GenPrimOp  Int# -> Float#
primop   Int2DoubleOp   "int2Double#"          GenPrimOp  Int# -> Double#

tibbe's avatar
tibbe committed
305 306 307
primop   Word2FloatOp   "word2Float#"      GenPrimOp  Word# -> Float#
primop   Word2DoubleOp   "word2Double#"          GenPrimOp  Word# -> Double#

308
primop   ISllOp   "uncheckedIShiftL#" GenPrimOp  Int# -> Int# -> Int#
309
         {Shift left.  Result undefined if shift amount is not
310
          in the range 0 to word size - 1 inclusive.}
311
primop   ISraOp   "uncheckedIShiftRA#" GenPrimOp Int# -> Int# -> Int#
312
         {Shift right arithmetic.  Result undefined if shift amount is not
313
          in the range 0 to word size - 1 inclusive.}
314
primop   ISrlOp   "uncheckedIShiftRL#" GenPrimOp Int# -> Int# -> Int#
315
         {Shift right logical.  Result undefined if shift amount is not
316
          in the range 0 to word size - 1 inclusive.}
317 318

------------------------------------------------------------------------
apt's avatar
apt committed
319
section "Word#"
320
        {Operations on native-sized unsigned words (32+ bits).}
321 322
------------------------------------------------------------------------

323 324
primtype Word#

apt's avatar
apt committed
325 326
primop   WordAddOp   "plusWord#"   Dyadic   Word# -> Word# -> Word#
   with commutable = True
327

Sebastian Graf's avatar
Sebastian Graf committed
328 329 330 331 332 333 334
primop   WordAddCOp   "addWordC#"   GenPrimOp   Word# -> Word# -> (# Word#, Int# #)
         {Add unsigned integers reporting overflow.
          The first element of the pair is the result.  The second element is
          the carry flag, which is nonzero on overflow. See also {\tt plusWord2#}.}
   with code_size = 2
        commutable = True

nkaretnikov's avatar
nkaretnikov committed
335 336 337 338
primop   WordSubCOp   "subWordC#"   GenPrimOp   Word# -> Word# -> (# Word#, Int# #)
         {Subtract unsigned integers reporting overflow.
          The first element of the pair is the result.  The second element is
          the carry flag, which is nonzero on overflow.}
Sebastian Graf's avatar
Sebastian Graf committed
339
   with code_size = 2
nkaretnikov's avatar
nkaretnikov committed
340

Sebastian Graf's avatar
Sebastian Graf committed
341 342 343 344 345 346
primop   WordAdd2Op   "plusWord2#"   GenPrimOp   Word# -> Word# -> (# Word#, Word# #)
         {Add unsigned integers, with the high part (carry) in the first
          component of the returned pair and the low part in the second
          component of the pair. See also {\tt addWordC#}.}
   with code_size = 2
        commutable = True
Ian Lynagh's avatar
Ian Lynagh committed
347

apt's avatar
apt committed
348 349 350
primop   WordSubOp   "minusWord#"   Dyadic   Word# -> Word# -> Word#

primop   WordMulOp   "timesWord#"   Dyadic   Word# -> Word# -> Word#
351 352
   with commutable = True

Ian Lynagh's avatar
Ian Lynagh committed
353
-- Returns (# high, low #)
Ian Lynagh's avatar
Ian Lynagh committed
354 355 356 357
primop   WordMul2Op  "timesWord2#"   GenPrimOp
   Word# -> Word# -> (# Word#, Word# #)
   with commutable = True

apt's avatar
apt committed
358 359 360 361 362 363
primop   WordQuotOp   "quotWord#"   Dyadic   Word# -> Word# -> Word#
   with can_fail = True

primop   WordRemOp   "remWord#"   Dyadic   Word# -> Word# -> Word#
   with can_fail = True

364 365 366 367
primop   WordQuotRemOp "quotRemWord#" GenPrimOp
   Word# -> Word# -> (# Word#, Word# #)
   with can_fail = True

Ian Lynagh's avatar
Ian Lynagh committed
368 369 370 371 372 373
-- Takes high word of dividend, then low word of dividend, then divisor.
-- Requires that high word is not divisible by divisor.
primop   WordQuotRem2Op "quotRemWord2#" GenPrimOp
   Word# -> Word# -> Word# -> (# Word#, Word# #)
   with can_fail = True

apt's avatar
apt committed
374
primop   AndOp   "and#"   Dyadic   Word# -> Word# -> Word#
375 376
   with commutable = True

apt's avatar
apt committed
377 378 379 380 381 382 383 384
primop   OrOp   "or#"   Dyadic   Word# -> Word# -> Word#
   with commutable = True

primop   XorOp   "xor#"   Dyadic   Word# -> Word# -> Word#
   with commutable = True

primop   NotOp   "not#"   Monadic   Word# -> Word#

385
primop   SllOp   "uncheckedShiftL#"   GenPrimOp   Word# -> Int# -> Word#
386
         {Shift left logical.   Result undefined if shift amount is not
387
          in the range 0 to word size - 1 inclusive.}
388
primop   SrlOp   "uncheckedShiftRL#"   GenPrimOp   Word# -> Int# -> Word#
389
         {Shift right logical.   Result undefined if shift  amount is not
390
          in the range 0 to word size - 1 inclusive.}
apt's avatar
apt committed
391 392

primop   Word2IntOp   "word2Int#"   GenPrimOp   Word# -> Int#
393
   with code_size = 0
apt's avatar
apt committed
394

395 396 397 398 399 400
primop   WordGtOp   "gtWord#"   Compare   Word# -> Word# -> Int#
primop   WordGeOp   "geWord#"   Compare   Word# -> Word# -> Int#
primop   WordEqOp   "eqWord#"   Compare   Word# -> Word# -> Int#
primop   WordNeOp   "neWord#"   Compare   Word# -> Word# -> Int#
primop   WordLtOp   "ltWord#"   Compare   Word# -> Word# -> Int#
primop   WordLeOp   "leWord#"   Compare   Word# -> Word# -> Int#
apt's avatar
apt committed
401

tibbe's avatar
tibbe committed
402 403 404 405 406 407
primop   PopCnt8Op   "popCnt8#"   Monadic   Word# -> Word#
    {Count the number of set bits in the lower 8 bits of a word.}
primop   PopCnt16Op   "popCnt16#"   Monadic   Word# -> Word#
    {Count the number of set bits in the lower 16 bits of a word.}
primop   PopCnt32Op   "popCnt32#"   Monadic   Word# -> Word#
    {Count the number of set bits in the lower 32 bits of a word.}
Simon Marlow's avatar
Simon Marlow committed
408
primop   PopCnt64Op   "popCnt64#"   GenPrimOp   WORD64 -> Word#
tibbe's avatar
tibbe committed
409 410 411 412
    {Count the number of set bits in a 64-bit word.}
primop   PopCntOp   "popCnt#"   Monadic   Word# -> Word#
    {Count the number of set bits in a word.}

413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434
primop   Pdep8Op   "pdep8#"   Dyadic   Word# -> Word# -> Word#
    {Deposit bits to lower 8 bits of a word at locations specified by a mask.}
primop   Pdep16Op   "pdep16#"   Dyadic   Word# -> Word# -> Word#
    {Deposit bits to lower 16 bits of a word at locations specified by a mask.}
primop   Pdep32Op   "pdep32#"   Dyadic   Word# -> Word# -> Word#
    {Deposit bits to lower 32 bits of a word at locations specified by a mask.}
primop   Pdep64Op   "pdep64#"   GenPrimOp   WORD64 -> WORD64 -> WORD64
    {Deposit bits to a word at locations specified by a mask.}
primop   PdepOp   "pdep#"   Dyadic   Word# -> Word# -> Word#
    {Deposit bits to a word at locations specified by a mask.}

primop   Pext8Op   "pext8#"   Dyadic   Word# -> Word# -> Word#
    {Extract bits from lower 8 bits of a word at locations specified by a mask.}
primop   Pext16Op   "pext16#"   Dyadic   Word# -> Word# -> Word#
    {Extract bits from lower 16 bits of a word at locations specified by a mask.}
primop   Pext32Op   "pext32#"   Dyadic   Word# -> Word# -> Word#
    {Extract bits from lower 32 bits of a word at locations specified by a mask.}
primop   Pext64Op   "pext64#"   GenPrimOp   WORD64 -> WORD64 -> WORD64
    {Extract bits from a word at locations specified by a mask.}
primop   PextOp   "pext#"   Dyadic   Word# -> Word# -> Word#
    {Extract bits from a word at locations specified by a mask.}

435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456
primop   Clz8Op   "clz8#" Monadic   Word# -> Word#
    {Count leading zeros in the lower 8 bits of a word.}
primop   Clz16Op   "clz16#" Monadic   Word# -> Word#
    {Count leading zeros in the lower 16 bits of a word.}
primop   Clz32Op   "clz32#" Monadic   Word# -> Word#
    {Count leading zeros in the lower 32 bits of a word.}
primop   Clz64Op   "clz64#" GenPrimOp WORD64 -> Word#
    {Count leading zeros in a 64-bit word.}
primop   ClzOp     "clz#"   Monadic   Word# -> Word#
    {Count leading zeros in a word.}

primop   Ctz8Op   "ctz8#"  Monadic   Word# -> Word#
    {Count trailing zeros in the lower 8 bits of a word.}
primop   Ctz16Op   "ctz16#" Monadic   Word# -> Word#
    {Count trailing zeros in the lower 16 bits of a word.}
primop   Ctz32Op   "ctz32#" Monadic   Word# -> Word#
    {Count trailing zeros in the lower 32 bits of a word.}
primop   Ctz64Op   "ctz64#" GenPrimOp WORD64 -> Word#
    {Count trailing zeros in a 64-bit word.}
primop   CtzOp     "ctz#"   Monadic   Word# -> Word#
    {Count trailing zeros in a word.}

457 458 459 460 461 462 463 464 465
primop   BSwap16Op   "byteSwap16#"   Monadic   Word# -> Word#
    {Swap bytes in the lower 16 bits of a word. The higher bytes are undefined. }
primop   BSwap32Op   "byteSwap32#"   Monadic   Word# -> Word#
    {Swap bytes in the lower 32 bits of a word. The higher bytes are undefined. }
primop   BSwap64Op   "byteSwap64#"   Monadic   WORD64 -> WORD64
    {Swap bytes in a 64 bits of a word.}
primop   BSwapOp     "byteSwap#"     Monadic   Word# -> Word#
    {Swap bytes in a word.}

apt's avatar
apt committed
466
------------------------------------------------------------------------
Jan Stolarek's avatar
Jan Stolarek committed
467
section "Narrowings"
468
        {Explicit narrowing of native-sized ints or words.}
apt's avatar
apt committed
469 470 471 472 473 474 475 476 477 478 479 480 481
------------------------------------------------------------------------

primop   Narrow8IntOp      "narrow8Int#"      Monadic   Int# -> Int#
primop   Narrow16IntOp     "narrow16Int#"     Monadic   Int# -> Int#
primop   Narrow32IntOp     "narrow32Int#"     Monadic   Int# -> Int#
primop   Narrow8WordOp     "narrow8Word#"     Monadic   Word# -> Word#
primop   Narrow16WordOp    "narrow16Word#"    Monadic   Word# -> Word#
primop   Narrow32WordOp    "narrow32Word#"    Monadic   Word# -> Word#


#if WORD_SIZE_IN_BITS < 64
------------------------------------------------------------------------
section "Int64#"
482 483 484
        {Operations on 64-bit unsigned words. This type is only used
         if plain {\tt Int\#} has less than 64 bits. In any case, the operations
         are not primops; they are implemented (if needed) as ccalls instead.}
apt's avatar
apt committed
485 486
------------------------------------------------------------------------

487 488
primtype Int64#

apt's avatar
apt committed
489 490
------------------------------------------------------------------------
section "Word64#"
491 492 493
        {Operations on 64-bit unsigned words. This type is only used
         if plain {\tt Word\#} has less than 64 bits. In any case, the operations
         are not primops; they are implemented (if needed) as ccalls instead.}
apt's avatar
apt committed
494 495
------------------------------------------------------------------------

496 497
primtype Word64#

apt's avatar
apt committed
498 499
#endif

500
------------------------------------------------------------------------
apt's avatar
apt committed
501
section "Double#"
502
        {Operations on double-precision (64 bit) floating-point numbers.}
503 504
------------------------------------------------------------------------

505 506
primtype Double#

507
primop   DoubleGtOp ">##"   Compare   Double# -> Double# -> Int#
508 509
   with fixity = infix 4

510
primop   DoubleGeOp ">=##"   Compare   Double# -> Double# -> Int#
511
   with fixity = infix 4
512

513
primop DoubleEqOp "==##"   Compare
514
   Double# -> Double# -> Int#
515
   with commutable = True
516
        fixity = infix 4
517

518
primop DoubleNeOp "/=##"   Compare
519
   Double# -> Double# -> Int#
520
   with commutable = True
521
        fixity = infix 4
522

523
primop   DoubleLtOp "<##"   Compare   Double# -> Double# -> Int#
524 525
   with fixity = infix 4

526
primop   DoubleLeOp "<=##"   Compare   Double# -> Double# -> Int#
527
   with fixity = infix 4
528 529 530 531

primop   DoubleAddOp   "+##"   Dyadic
   Double# -> Double# -> Double#
   with commutable = True
532
        fixity = infixl 6
533 534

primop   DoubleSubOp   "-##"   Dyadic   Double# -> Double# -> Double#
535
   with fixity = infixl 6
536 537 538 539

primop   DoubleMulOp   "*##"   Dyadic
   Double# -> Double# -> Double#
   with commutable = True
540
        fixity = infixl 7
541 542 543 544

primop   DoubleDivOp   "/##"   Dyadic
   Double# -> Double# -> Double#
   with can_fail = True
545
        fixity = infixl 7
546 547 548

primop   DoubleNegOp   "negateDouble#"  Monadic   Double# -> Double#

549 550
primop   DoubleFabsOp  "fabsDouble#"    Monadic   Double# -> Double#

551
primop   Double2IntOp   "double2Int#"          GenPrimOp  Double# -> Int#
552 553 554 555
   {Truncates a {\tt Double#} value to the nearest {\tt Int#}.
    Results are undefined if the truncation if truncation yields
    a value outside the range of {\tt Int#}.}

556 557 558 559
primop   Double2FloatOp   "double2Float#" GenPrimOp Double# -> Float#

primop   DoubleExpOp   "expDouble#"      Monadic
   Double# -> Double#
560 561
   with
   code_size = { primOpCodeSizeForeignCall }
562

Jan Stolarek's avatar
Jan Stolarek committed
563
primop   DoubleLogOp   "logDouble#"      Monadic
564 565
   Double# -> Double#
   with
566
   code_size = { primOpCodeSizeForeignCall }
567 568
   can_fail = True

Jan Stolarek's avatar
Jan Stolarek committed
569
primop   DoubleSqrtOp   "sqrtDouble#"      Monadic
570
   Double# -> Double#
571 572
   with
   code_size = { primOpCodeSizeForeignCall }
573

Jan Stolarek's avatar
Jan Stolarek committed
574
primop   DoubleSinOp   "sinDouble#"      Monadic
575
   Double# -> Double#
576 577
   with
   code_size = { primOpCodeSizeForeignCall }
578

Jan Stolarek's avatar
Jan Stolarek committed
579
primop   DoubleCosOp   "cosDouble#"      Monadic
580
   Double# -> Double#
581 582
   with
   code_size = { primOpCodeSizeForeignCall }
583

Jan Stolarek's avatar
Jan Stolarek committed
584
primop   DoubleTanOp   "tanDouble#"      Monadic
585
   Double# -> Double#
586 587
   with
   code_size = { primOpCodeSizeForeignCall }
588

Jan Stolarek's avatar
Jan Stolarek committed
589
primop   DoubleAsinOp   "asinDouble#"      Monadic
590 591
   Double# -> Double#
   with
592
   code_size = { primOpCodeSizeForeignCall }
593 594
   can_fail = True

Jan Stolarek's avatar
Jan Stolarek committed
595
primop   DoubleAcosOp   "acosDouble#"      Monadic
596 597
   Double# -> Double#
   with
598
   code_size = { primOpCodeSizeForeignCall }
599 600
   can_fail = True

Jan Stolarek's avatar
Jan Stolarek committed
601
primop   DoubleAtanOp   "atanDouble#"      Monadic
602 603
   Double# -> Double#
   with
604
   code_size = { primOpCodeSizeForeignCall }
605

Jan Stolarek's avatar
Jan Stolarek committed
606
primop   DoubleSinhOp   "sinhDouble#"      Monadic
607
   Double# -> Double#
608 609
   with
   code_size = { primOpCodeSizeForeignCall }
610

Jan Stolarek's avatar
Jan Stolarek committed
611
primop   DoubleCoshOp   "coshDouble#"      Monadic
612
   Double# -> Double#
613 614
   with
   code_size = { primOpCodeSizeForeignCall }
615

Jan Stolarek's avatar
Jan Stolarek committed
616
primop   DoubleTanhOp   "tanhDouble#"      Monadic
617
   Double# -> Double#
618 619
   with
   code_size = { primOpCodeSizeForeignCall }
620

621 622 623 624 625 626 627 628 629 630 631 632 633 634 635
primop   DoubleAsinhOp   "asinhDouble#"      Monadic
   Double# -> Double#
   with
   code_size = { primOpCodeSizeForeignCall }

primop   DoubleAcoshOp   "acoshDouble#"      Monadic
   Double# -> Double#
   with
   code_size = { primOpCodeSizeForeignCall }

primop   DoubleAtanhOp   "atanhDouble#"      Monadic
   Double# -> Double#
   with
   code_size = { primOpCodeSizeForeignCall }

Jan Stolarek's avatar
Jan Stolarek committed
636
primop   DoublePowerOp   "**##" Dyadic
637
   Double# -> Double# -> Double#
apt's avatar
apt committed
638
   {Exponentiation.}
639 640
   with
   code_size = { primOpCodeSizeForeignCall }
641

Jan Stolarek's avatar
Jan Stolarek committed
642
primop   DoubleDecode_2IntOp   "decodeDouble_2Int#" GenPrimOp
643
   Double# -> (# Int#, Word#, Word#, Int# #)
644
   {Convert to integer.
645 646 647
    First component of the result is -1 or 1, indicating the sign of the
    mantissa. The next two are the high and low 32 bits of the mantissa
    respectively, and the last is the exponent.}
648 649
   with out_of_line = True

650 651 652 653 654
primop   DoubleDecode_Int64Op   "decodeDouble_Int64#" GenPrimOp
   Double# -> (# INT64, Int# #)
   {Decode {\tt Double\#} into mantissa and base-2 exponent.}
   with out_of_line = True

655
------------------------------------------------------------------------
656
section "Float#"
657
        {Operations on single-precision (32-bit) floating-point numbers.}
658 659
------------------------------------------------------------------------

660 661
primtype Float#

662 663
primop   FloatGtOp  "gtFloat#"   Compare   Float# -> Float# -> Int#
primop   FloatGeOp  "geFloat#"   Compare   Float# -> Float# -> Int#
664

665
primop   FloatEqOp  "eqFloat#"   Compare
666
   Float# -> Float# -> Int#
667 668
   with commutable = True

669
primop   FloatNeOp  "neFloat#"   Compare
670
   Float# -> Float# -> Int#
671 672
   with commutable = True

673 674
primop   FloatLtOp  "ltFloat#"   Compare   Float# -> Float# -> Int#
primop   FloatLeOp  "leFloat#"   Compare   Float# -> Float# -> Int#
675

676
primop   FloatAddOp   "plusFloat#"      Dyadic
677 678 679 680 681
   Float# -> Float# -> Float#
   with commutable = True

primop   FloatSubOp   "minusFloat#"      Dyadic      Float# -> Float# -> Float#

682
primop   FloatMulOp   "timesFloat#"      Dyadic
683 684 685
   Float# -> Float# -> Float#
   with commutable = True

686
primop   FloatDivOp   "divideFloat#"      Dyadic
687 688 689 690 691
   Float# -> Float# -> Float#
   with can_fail = True

primop   FloatNegOp   "negateFloat#"      Monadic    Float# -> Float#

692 693
primop   FloatFabsOp  "fabsFloat#"        Monadic    Float# -> Float#

694
primop   Float2IntOp   "float2Int#"      GenPrimOp  Float# -> Int#
695 696 697
   {Truncates a {\tt Float#} value to the nearest {\tt Int#}.
    Results are undefined if the truncation if truncation yields
    a value outside the range of {\tt Int#}.}
698

Jan Stolarek's avatar
Jan Stolarek committed
699
primop   FloatExpOp   "expFloat#"      Monadic
700
   Float# -> Float#
701 702
   with
   code_size = { primOpCodeSizeForeignCall }
703

Jan Stolarek's avatar
Jan Stolarek committed
704
primop   FloatLogOp   "logFloat#"      Monadic
705
   Float# -> Float#
706 707 708
   with
   code_size = { primOpCodeSizeForeignCall }
   can_fail = True
709

Jan Stolarek's avatar
Jan Stolarek committed
710
primop   FloatSqrtOp   "sqrtFloat#"      Monadic
711
   Float# -> Float#
712 713
   with
   code_size = { primOpCodeSizeForeignCall }
714

Jan Stolarek's avatar
Jan Stolarek committed
715
primop   FloatSinOp   "sinFloat#"      Monadic
716
   Float# -> Float#
717 718
   with
   code_size = { primOpCodeSizeForeignCall }
719

Jan Stolarek's avatar
Jan Stolarek committed
720
primop   FloatCosOp   "cosFloat#"      Monadic
721
   Float# -> Float#
722 723
   with
   code_size = { primOpCodeSizeForeignCall }
724

Jan Stolarek's avatar
Jan Stolarek committed
725
primop   FloatTanOp   "tanFloat#"      Monadic
726
   Float# -> Float#
727 728
   with
   code_size = { primOpCodeSizeForeignCall }
729

Jan Stolarek's avatar
Jan Stolarek committed
730
primop   FloatAsinOp   "asinFloat#"      Monadic
731
   Float# -> Float#
732 733 734
   with
   code_size = { primOpCodeSizeForeignCall }
   can_fail = True
735

Jan Stolarek's avatar
Jan Stolarek committed
736
primop   FloatAcosOp   "acosFloat#"      Monadic
737
   Float# -> Float#
738 739 740
   with
   code_size = { primOpCodeSizeForeignCall }
   can_fail = True
741

Jan Stolarek's avatar
Jan Stolarek committed
742
primop   FloatAtanOp   "atanFloat#"      Monadic
743
   Float# -> Float#
744 745
   with
   code_size = { primOpCodeSizeForeignCall }
746

Jan Stolarek's avatar
Jan Stolarek committed
747
primop   FloatSinhOp   "sinhFloat#"      Monadic
748
   Float# -> Float#
749 750
   with
   code_size = { primOpCodeSizeForeignCall }
751

Jan Stolarek's avatar
Jan Stolarek committed
752
primop   FloatCoshOp   "coshFloat#"      Monadic
753
   Float# -> Float#
754 755
   with
   code_size = { primOpCodeSizeForeignCall }
756

Jan Stolarek's avatar
Jan Stolarek committed
757
primop   FloatTanhOp   "tanhFloat#"      Monadic
758
   Float# -> Float#
759 760
   with
   code_size = { primOpCodeSizeForeignCall }
761

762 763 764 765 766 767 768 769 770 771 772 773 774 775 776
primop   FloatAsinhOp   "asinhFloat#"      Monadic
   Float# -> Float#
   with
   code_size = { primOpCodeSizeForeignCall }

primop   FloatAcoshOp   "acoshFloat#"      Monadic
   Float# -> Float#
   with
   code_size = { primOpCodeSizeForeignCall }

primop   FloatAtanhOp   "atanhFloat#"      Monadic
   Float# -> Float#
   with
   code_size = { primOpCodeSizeForeignCall }

Jan Stolarek's avatar
Jan Stolarek committed
777
primop   FloatPowerOp   "powerFloat#"      Dyadic
778
   Float# -> Float# -> Float#
779 780
   with
   code_size = { primOpCodeSizeForeignCall }
781 782 783

primop   Float2DoubleOp   "float2Double#" GenPrimOp  Float# -> Double#

784 785
primop   FloatDecode_IntOp   "decodeFloat_Int#" GenPrimOp
   Float# -> (# Int#, Int# #)
786
   {Convert to integers.
787 788 789
    First {\tt Int\#} in result is the mantissa; second is the exponent.}
   with out_of_line = True

790
------------------------------------------------------------------------
apt's avatar
apt committed
791
section "Arrays"
792
        {Operations on {\tt Array\#}.}
793 794
------------------------------------------------------------------------

795 796
primtype Array# a

797
primtype MutableArray# s a
798

apt's avatar
apt committed
799
primop  NewArrayOp "newArray#" GenPrimOp
800
   Int# -> a -> State# s -> (# State# s, MutableArray# s a #)
801
   {Create a new mutable array with the specified number of elements,
apt's avatar
apt committed
802 803 804 805
    in the specified state thread,
    with each element containing the specified initial value.}
   with
   out_of_line = True
806
   has_side_effects = True
807

apt's avatar
apt committed
808
primop  SameMutableArrayOp "sameMutableArray#" GenPrimOp
809
   MutableArray# s a -> MutableArray# s a -> Int#
810

apt's avatar
apt committed
811
primop  ReadArrayOp "readArray#" GenPrimOp
812
   MutableArray# s a -> Int# -> State# s -> (# State# s, a #)
apt's avatar
apt committed
813
   {Read from specified index of mutable array. Result is not yet evaluated.}
814 815
   with
   has_side_effects = True
816
   can_fail         = True
817

apt's avatar
apt committed
818
primop  WriteArrayOp "writeArray#" GenPrimOp
819
   MutableArray# s a -> Int# -> a -> State# s -> State# s
apt's avatar
apt committed
820 821 822
   {Write to specified index of mutable array.}
   with
   has_side_effects = True
823 824
   can_fail         = True
   code_size        = 2 -- card update too
825

pumpkin's avatar
pumpkin committed
826 827 828 829 830 831 832 833
primop  SizeofArrayOp "sizeofArray#" GenPrimOp
   Array# a -> Int#
   {Return the number of elements in the array.}

primop  SizeofMutableArrayOp "sizeofMutableArray#" GenPrimOp
   MutableArray# s a -> Int#
   {Return the number of elements in the array.}

apt's avatar
apt committed
834 835
primop  IndexArrayOp "indexArray#" GenPrimOp
   Array# a -> Int# -> (# a #)
836 837 838 839 840 841 842
   {Read from the specified index of an immutable array. The result is packaged
    into an unboxed unary tuple; the result itself is not yet
    evaluated. Pattern matching on the tuple forces the indexing of the
    array to happen but does not evaluate the element itself. Evaluating
    the thunk prevents additional thunks from building up on the
    heap. Avoiding these thunks, in turn, reduces references to the
    argument array, allowing it to be garbage collected more promptly.}
843 844
   with
   can_fail         = True
845

apt's avatar
apt committed
846
primop  UnsafeFreezeArrayOp "unsafeFreezeArray#" GenPrimOp
847
   MutableArray# s a -> State# s -> (# State# s, Array# a #)
apt's avatar
apt committed
848 849 850
   {Make a mutable array immutable, without copying.}
   with
   has_side_effects = True
851

apt's avatar
apt committed
852
primop  UnsafeThawArrayOp  "unsafeThawArray#" GenPrimOp
853
   Array# a -> State# s -> (# State# s, MutableArray# s a #)
apt's avatar
apt committed
854 855 856
   {Make an immutable array mutable, without copying.}
   with
   out_of_line = True
857
   has_side_effects = True
858

pumpkin's avatar
pumpkin committed
859 860
primop  CopyArrayOp "copyArray#" GenPrimOp
  Array# a -> Int# -> MutableArray# s a -> Int# -> Int# -> State# s -> State# s
tibbe's avatar
tibbe committed
861 862 863 864 865 866 867
  {Given a source array, an offset into the source array, a
   destination array, an offset into the destination array, and a
   number of elements to copy, copy the elements from the source array
   to the destination array. Both arrays must fully contain the
   specified ranges, but this is not checked. The two arrays must not
   be the same array in different states, but this is not checked
   either.}
pumpkin's avatar
pumpkin committed
868
  with
869
  out_of_line      = True
pumpkin's avatar
pumpkin committed
870
  has_side_effects = True
871
  can_fail         = True
pumpkin's avatar
pumpkin committed
872 873 874

primop  CopyMutableArrayOp "copyMutableArray#" GenPrimOp
  MutableArray# s a -> Int# -> MutableArray# s a -> Int# -> Int# -> State# s -> State# s
tibbe's avatar
tibbe committed
875 876 877
  {Given a source array, an offset into the source array, a
   destination array, an offset into the destination array, and a
   number of elements to copy, copy the elements from the source array
878 879 880 881
   to the destination array. Both arrays must fully contain the
   specified ranges, but this is not checked. In the case where
   the source and destination are the same array the source and
   destination regions may overlap.}
pumpkin's avatar
pumpkin committed
882
  with
883
  out_of_line      = True
pumpkin's avatar
pumpkin committed
884
  has_side_effects = True
885
  can_fail         = True
pumpkin's avatar
pumpkin committed
886 887 888

primop  CloneArrayOp "cloneArray#" GenPrimOp
  Array# a -> Int# -> Int# -> Array# a
tibbe's avatar
tibbe committed
889 890 891 892
  {Given a source array, an offset into the source array, and a number
   of elements to copy, create a new array with the elements from the
   source array. The provided array must fully contain the specified
   range, but this is not checked.}
pumpkin's avatar
pumpkin committed
893
  with
894
  out_of_line      = True
pumpkin's avatar
pumpkin committed
895
  has_side_effects = True
896
  can_fail         = True
pumpkin's avatar
pumpkin committed
897 898 899

primop  CloneMutableArrayOp "cloneMutableArray#" GenPrimOp
  MutableArray# s a -> Int# -> Int# -> State# s -> (# State# s, MutableArray# s a #)
tibbe's avatar
tibbe committed
900 901 902 903
  {Given a source array, an offset into the source array, and a number
   of elements to copy, create a new array with the elements from the
   source array. The provided array must fully contain the specified
   range, but this is not checked.}
pumpkin's avatar
pumpkin committed
904
  with
905
  out_of_line      = True
pumpkin's avatar
pumpkin committed
906
  has_side_effects = True
907
  can_fail         = True
pumpkin's avatar
pumpkin committed
908 909 910

primop  FreezeArrayOp "freezeArray#" GenPrimOp
  MutableArray# s a -> Int# -> Int# -> State# s -> (# State# s, Array# a #)
tibbe's avatar
tibbe committed
911 912 913 914
  {Given a source array, an offset into the source array, and a number
   of elements to copy, create a new array with the elements from the
   source array. The provided array must fully contain the specified
   range, but this is not checked.}
pumpkin's avatar
pumpkin committed
915
  with
916
  out_of_line      = True
pumpkin's avatar
pumpkin committed
917
  has_side_effects = True
918
  can_fail         = True
pumpkin's avatar
pumpkin committed
919 920 921

primop  ThawArrayOp "thawArray#" GenPrimOp
  Array# a -> Int# -> Int# -> State# s -> (# State# s, MutableArray# s a #)
tibbe's avatar
tibbe committed
922 923 924 925
  {Given a source array, an offset into the source array, and a number
   of elements to copy, create a new array with the elements from the
   source array. The provided array must fully contain the specified
   range, but this is not checked.}
pumpkin's avatar
pumpkin committed
926
  with
927
  out_of_line      = True
pumpkin's avatar
pumpkin committed
928
  has_side_effects = True
929
  can_fail         = True
pumpkin's avatar
pumpkin committed
930

931 932 933 934 935 936 937 938