e1a9824a161ebcbfeb184929ddcfc96f58a87194
[ghc.git] / compiler / prelude / primops.txt.pp
1 -----------------------------------------------------------------------
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
12 -- This file is processed by the utility program genprimopcode to produce
13 -- a number of include files within the compiler and optionally to produce
14 -- human-readable documentation.
15 --
16 -- It should first be preprocessed.
17 --
18 -- Information on how PrimOps are implemented and the steps necessary to
19 -- add a new one can be found in the Commentary:
20 --
21 --  http://ghc.haskell.org/trac/ghc/wiki/Commentary/PrimOps
22
23 -- This file is divided into named sections, each containing or more
24 -- primop entries. Section headers have the format:
25 --
26 --      section "section-name" {description}
27 --
28 -- This information is used solely when producing documentation; it is
29 -- otherwise ignored.  The description is optional.
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
35 -- The default attribute values which apply if you don't specify
36 -- other ones.  Attribute values can be True, False, or arbitrary
37 -- text between curly brackets.  This is a kludge to enable
38 -- processors of this file to easily get hold of simple info
39 -- (eg, out_of_line), whilst avoiding parsing complex expressions
40 -- needed for strictness info.
41
42 -- The vector attribute is rather special. It takes a list of 3-tuples, each of
43 -- which is of the form <ELEM_TYPE,SCALAR_TYPE,LENGTH>. ELEM_TYPE is the type of
44 -- the elements in the vector; LENGTH is the length of the vector; and
45 -- SCALAR_TYPE is the scalar type used to inject to/project from vector
46 -- element. Note that ELEM_TYPE and SCALAR_TYPE are not the same; for example,
47 -- to broadcast a scalar value to a vector whose elements are of type Int8, we
48 -- use an Int#.
49
50 -- When a primtype or primop has a vector attribute, it is instantiated at each
51 -- 3-tuple in the list of 3-tuples. That is, the vector attribute allows us to
52 -- define a family of types or primops. Vector support also adds three new
53 -- keywords: VECTOR, SCALAR, and VECTUPLE. These keywords are expanded to types
54 -- derived from the 3-tuple. For the 3-tuple <Int64,INT64,2>, VECTOR expands to
55 -- Int64X2#, SCALAR expands to INT64, and VECTUPLE expands to (# INT64, INT64
56 -- #).
57
58 defaults
59    has_side_effects = False
60    out_of_line      = False   -- See Note Note [PrimOp can_fail and has_side_effects] in PrimOp
61    can_fail         = False   -- See Note Note [PrimOp can_fail and has_side_effects] in PrimOp
62    commutable       = False
63    code_size        = { primOpCodeSizeDefault }
64    strictness       = { \ arity -> mkClosedStrictSig (replicate arity topDmd) topRes }
65    fixity           = Nothing
66    llvm_only        = False
67    vector           = []
68
69 -- Currently, documentation is produced using latex, so contents of
70 -- description fields should be legal latex. Descriptions can contain
71 -- matched pairs of embedded curly brackets.
72
73 #include "MachDeps.h"
74
75 -- We need platform defines (tests for mingw32 below).
76 #include "ghc_boot_platform.h"
77
78 section "The word size story."
79         {Haskell98 specifies that signed integers (type {\tt Int})
80          must contain at least 30 bits. GHC always implements {\tt
81          Int} using the primitive type {\tt Int\#}, whose size equals
82          the {\tt MachDeps.h} constant {\tt WORD\_SIZE\_IN\_BITS}.
83          This is normally set based on the {\tt config.h} parameter
84          {\tt SIZEOF\_HSWORD}, i.e., 32 bits on 32-bit machines, 64
85          bits on 64-bit machines.  However, it can also be explicitly
86          set to a smaller number, e.g., 31 bits, to allow the
87          possibility of using tag bits. Currently GHC itself has only
88          32-bit and 64-bit variants, but 30 or 31-bit code can be
89          exported as an external core file for use in other back ends.
90
91          GHC also implements a primitive unsigned integer type {\tt
92          Word\#} which always has the same number of bits as {\tt
93          Int\#}.
94
95          In addition, GHC supports families of explicit-sized integers
96          and words at 8, 16, 32, and 64 bits, with the usual
97          arithmetic operations, comparisons, and a range of
98          conversions.  The 8-bit and 16-bit sizes are always
99          represented as {\tt Int\#} and {\tt Word\#}, and the
100          operations implemented in terms of the the primops on these
101          types, with suitable range restrictions on the results (using
102          the {\tt narrow$n$Int\#} and {\tt narrow$n$Word\#} families
103          of primops.  The 32-bit sizes are represented using {\tt
104          Int\#} and {\tt Word\#} when {\tt WORD\_SIZE\_IN\_BITS}
105          $\geq$ 32; otherwise, these are represented using distinct
106          primitive types {\tt Int32\#} and {\tt Word32\#}. These (when
107          needed) have a complete set of corresponding operations;
108          however, nearly all of these are implemented as external C
109          functions rather than as primops.  Exactly the same story
110          applies to the 64-bit sizes.  All of these details are hidden
111          under the {\tt PrelInt} and {\tt PrelWord} modules, which use
112          {\tt \#if}-defs to invoke the appropriate types and
113          operators.
114
115          Word size also matters for the families of primops for
116          indexing/reading/writing fixed-size quantities at offsets
117          from an array base, address, or foreign pointer.  Here, a
118          slightly different approach is taken.  The names of these
119          primops are fixed, but their {\it types} vary according to
120          the value of {\tt WORD\_SIZE\_IN\_BITS}. For example, if word
121          size is at least 32 bits then an operator like
122          \texttt{indexInt32Array\#} has type {\tt ByteArray\# -> Int\#
123          -> Int\#}; otherwise it has type {\tt ByteArray\# -> Int\# ->
124          Int32\#}.  This approach confines the necessary {\tt
125          \#if}-defs to this file; no conditional compilation is needed
126          in the files that expose these primops.
127
128          Finally, there are strongly deprecated primops for coercing
129          between {\tt Addr\#}, the primitive type of machine
130          addresses, and {\tt Int\#}.  These are pretty bogus anyway,
131          but will work on existing 32-bit and 64-bit GHC targets; they
132          are completely bogus when tag bits are used in {\tt Int\#},
133          so are not available in this case.  }
134
135 -- Define synonyms for indexing ops.
136
137 #if WORD_SIZE_IN_BITS < 32
138 #define INT32 Int32#
139 #define WORD32 Word32#
140 #else
141 #define INT32 Int#
142 #define WORD32 Word#
143 #endif
144
145 #if WORD_SIZE_IN_BITS < 64
146 #define INT64 Int64#
147 #define WORD64 Word64#
148 #else
149 #define INT64 Int#
150 #define WORD64 Word#
151 #endif
152
153 ------------------------------------------------------------------------
154 section "Char#"
155         {Operations on 31-bit characters.}
156 ------------------------------------------------------------------------
157
158 primtype Char#
159
160 primop   CharGtOp  "gtChar#"   Compare   Char# -> Char# -> Int#
161 primop   CharGeOp  "geChar#"   Compare   Char# -> Char# -> Int#
162
163 primop   CharEqOp  "eqChar#"   Compare
164    Char# -> Char# -> Int#
165    with commutable = True
166
167 primop   CharNeOp  "neChar#"   Compare
168    Char# -> Char# -> Int#
169    with commutable = True
170
171 primop   CharLtOp  "ltChar#"   Compare   Char# -> Char# -> Int#
172 primop   CharLeOp  "leChar#"   Compare   Char# -> Char# -> Int#
173
174 primop   OrdOp   "ord#"  GenPrimOp   Char# -> Int#
175    with code_size = 0
176
177 ------------------------------------------------------------------------
178 section "Int#"
179         {Operations on native-size integers (30+ bits).}
180 ------------------------------------------------------------------------
181
182 primtype Int#
183
184 primop   IntAddOp    "+#"    Dyadic
185    Int# -> Int# -> Int#
186    with commutable = True
187         fixity = infixl 6
188
189 primop   IntSubOp    "-#"    Dyadic   Int# -> Int# -> Int#
190    with fixity = infixl 6
191
192 primop   IntMulOp    "*#"
193    Dyadic   Int# -> Int# -> Int#
194    {Low word of signed integer multiply.}
195    with commutable = True
196         fixity = infixl 7
197
198 primop   IntMulMayOfloOp  "mulIntMayOflo#"
199    Dyadic   Int# -> Int# -> Int#
200    {Return non-zero if there is any possibility that the upper word of a
201     signed integer multiply might contain useful information.  Return
202     zero only if you are completely sure that no overflow can occur.
203     On a 32-bit platform, the recommmended implementation is to do a
204     32 x 32 -> 64 signed multiply, and subtract result[63:32] from
205     (result[31] >>signed 31).  If this is zero, meaning that the
206     upper word is merely a sign extension of the lower one, no
207     overflow can occur.
208
209     On a 64-bit platform it is not always possible to
210     acquire the top 64 bits of the result.  Therefore, a recommended
211     implementation is to take the absolute value of both operands, and
212     return 0 iff bits[63:31] of them are zero, since that means that their
213     magnitudes fit within 31 bits, so the magnitude of the product must fit
214     into 62 bits.
215
216     If in doubt, return non-zero, but do make an effort to create the
217     correct answer for small args, since otherwise the performance of
218     \texttt{(*) :: Integer -> Integer -> Integer} will be poor.
219    }
220    with commutable = True
221
222 primop   IntQuotOp    "quotInt#"    Dyadic
223    Int# -> Int# -> Int#
224    {Rounds towards zero.}
225    with can_fail = True
226
227 primop   IntRemOp    "remInt#"    Dyadic
228    Int# -> Int# -> Int#
229    {Satisfies \texttt{(quotInt\# x y) *\# y +\# (remInt\# x y) == x}.}
230    with can_fail = True
231
232 primop   IntQuotRemOp "quotRemInt#"    GenPrimOp
233    Int# -> Int# -> (# Int#, Int# #)
234    {Rounds towards zero.}
235    with can_fail = True
236
237 primop   AndIOp   "andI#"   Dyadic    Int# -> Int# -> Int#
238    with commutable = True
239
240 primop   OrIOp   "orI#"     Dyadic    Int# -> Int# -> Int#
241    with commutable = True
242
243 primop   XorIOp   "xorI#"   Dyadic    Int# -> Int# -> Int#
244    with commutable = True
245
246 primop   NotIOp   "notI#"   Monadic   Int# -> Int#
247
248 primop   IntNegOp    "negateInt#"    Monadic   Int# -> Int#
249 primop   IntAddCOp   "addIntC#"    GenPrimOp   Int# -> Int# -> (# Int#, Int# #)
250          {Add with carry.  First member of result is (wrapped) sum;
251           second member is 0 iff no overflow occured.}
252    with code_size = 2
253
254 primop   IntSubCOp   "subIntC#"    GenPrimOp   Int# -> Int# -> (# Int#, Int# #)
255          {Subtract with carry.  First member of result is (wrapped) difference;
256           second member is 0 iff no overflow occured.}
257    with code_size = 2
258
259 primop   IntGtOp  ">#"   Compare   Int# -> Int# -> Int#
260    with fixity = infix 4
261
262 primop   IntGeOp  ">=#"   Compare   Int# -> Int# -> Int#
263    with fixity = infix 4
264
265 primop   IntEqOp  "==#"   Compare
266    Int# -> Int# -> Int#
267    with commutable = True
268         fixity = infix 4
269
270 primop   IntNeOp  "/=#"   Compare
271    Int# -> Int# -> Int#
272    with commutable = True
273         fixity = infix 4
274
275 primop   IntLtOp  "<#"   Compare   Int# -> Int# -> Int#
276    with fixity = infix 4
277
278 primop   IntLeOp  "<=#"   Compare   Int# -> Int# -> Int#
279    with fixity = infix 4
280
281 primop   ChrOp   "chr#"   GenPrimOp   Int# -> Char#
282    with code_size = 0
283
284 primop   Int2WordOp "int2Word#" GenPrimOp Int# -> Word#
285    with code_size = 0
286
287 primop   Int2FloatOp   "int2Float#"      GenPrimOp  Int# -> Float#
288 primop   Int2DoubleOp   "int2Double#"          GenPrimOp  Int# -> Double#
289
290 primop   Word2FloatOp   "word2Float#"      GenPrimOp  Word# -> Float#
291 primop   Word2DoubleOp   "word2Double#"          GenPrimOp  Word# -> Double#
292
293 primop   ISllOp   "uncheckedIShiftL#" GenPrimOp  Int# -> Int# -> Int#
294          {Shift left.  Result undefined if shift amount is not
295           in the range 0 to word size - 1 inclusive.}
296 primop   ISraOp   "uncheckedIShiftRA#" GenPrimOp Int# -> Int# -> Int#
297          {Shift right arithmetic.  Result undefined if shift amount is not
298           in the range 0 to word size - 1 inclusive.}
299 primop   ISrlOp   "uncheckedIShiftRL#" GenPrimOp Int# -> Int# -> Int#
300          {Shift right logical.  Result undefined if shift amount is not
301           in the range 0 to word size - 1 inclusive.}
302
303 ------------------------------------------------------------------------
304 section "Word#"
305         {Operations on native-sized unsigned words (30+ bits).}
306 ------------------------------------------------------------------------
307
308 primtype Word#
309
310 primop   WordAddOp   "plusWord#"   Dyadic   Word# -> Word# -> Word#
311    with commutable = True
312
313 -- Returns (# high, low #) (or equivalently, (# carry, low #))
314 primop   WordAdd2Op  "plusWord2#"  GenPrimOp
315    Word# -> Word# -> (# Word#, Word# #)
316    with commutable = True
317
318 primop   WordSubOp   "minusWord#"   Dyadic   Word# -> Word# -> Word#
319
320 primop   WordMulOp   "timesWord#"   Dyadic   Word# -> Word# -> Word#
321    with commutable = True
322
323 -- Returns (# high, low #)
324 primop   WordMul2Op  "timesWord2#"   GenPrimOp
325    Word# -> Word# -> (# Word#, Word# #)
326    with commutable = True
327
328 primop   WordQuotOp   "quotWord#"   Dyadic   Word# -> Word# -> Word#
329    with can_fail = True
330
331 primop   WordRemOp   "remWord#"   Dyadic   Word# -> Word# -> Word#
332    with can_fail = True
333
334 primop   WordQuotRemOp "quotRemWord#" GenPrimOp
335    Word# -> Word# -> (# Word#, Word# #)
336    with can_fail = True
337
338 -- Takes high word of dividend, then low word of dividend, then divisor.
339 -- Requires that high word is not divisible by divisor.
340 primop   WordQuotRem2Op "quotRemWord2#" GenPrimOp
341    Word# -> Word# -> Word# -> (# Word#, Word# #)
342    with can_fail = True
343
344 primop   AndOp   "and#"   Dyadic   Word# -> Word# -> Word#
345    with commutable = True
346
347 primop   OrOp   "or#"   Dyadic   Word# -> Word# -> Word#
348    with commutable = True
349
350 primop   XorOp   "xor#"   Dyadic   Word# -> Word# -> Word#
351    with commutable = True
352
353 primop   NotOp   "not#"   Monadic   Word# -> Word#
354
355 primop   SllOp   "uncheckedShiftL#"   GenPrimOp   Word# -> Int# -> Word#
356          {Shift left logical.   Result undefined if shift amount is not
357           in the range 0 to word size - 1 inclusive.}
358 primop   SrlOp   "uncheckedShiftRL#"   GenPrimOp   Word# -> Int# -> Word#
359          {Shift right logical.   Result undefined if shift  amount is not
360           in the range 0 to word size - 1 inclusive.}
361
362 primop   Word2IntOp   "word2Int#"   GenPrimOp   Word# -> Int#
363    with code_size = 0
364
365 primop   WordGtOp   "gtWord#"   Compare   Word# -> Word# -> Int#
366 primop   WordGeOp   "geWord#"   Compare   Word# -> Word# -> Int#
367 primop   WordEqOp   "eqWord#"   Compare   Word# -> Word# -> Int#
368 primop   WordNeOp   "neWord#"   Compare   Word# -> Word# -> Int#
369 primop   WordLtOp   "ltWord#"   Compare   Word# -> Word# -> Int#
370 primop   WordLeOp   "leWord#"   Compare   Word# -> Word# -> Int#
371
372 primop   PopCnt8Op   "popCnt8#"   Monadic   Word# -> Word#
373     {Count the number of set bits in the lower 8 bits of a word.}
374 primop   PopCnt16Op   "popCnt16#"   Monadic   Word# -> Word#
375     {Count the number of set bits in the lower 16 bits of a word.}
376 primop   PopCnt32Op   "popCnt32#"   Monadic   Word# -> Word#
377     {Count the number of set bits in the lower 32 bits of a word.}
378 primop   PopCnt64Op   "popCnt64#"   GenPrimOp   WORD64 -> Word#
379     {Count the number of set bits in a 64-bit word.}
380 primop   PopCntOp   "popCnt#"   Monadic   Word# -> Word#
381     {Count the number of set bits in a word.}
382
383 primop   BSwap16Op   "byteSwap16#"   Monadic   Word# -> Word#
384     {Swap bytes in the lower 16 bits of a word. The higher bytes are undefined. }
385 primop   BSwap32Op   "byteSwap32#"   Monadic   Word# -> Word#
386     {Swap bytes in the lower 32 bits of a word. The higher bytes are undefined. }
387 primop   BSwap64Op   "byteSwap64#"   Monadic   WORD64 -> WORD64
388     {Swap bytes in a 64 bits of a word.}
389 primop   BSwapOp     "byteSwap#"     Monadic   Word# -> Word#
390     {Swap bytes in a word.}
391
392 ------------------------------------------------------------------------
393 section "Narrowings"
394         {Explicit narrowing of native-sized ints or words.}
395 ------------------------------------------------------------------------
396
397 primop   Narrow8IntOp      "narrow8Int#"      Monadic   Int# -> Int#
398 primop   Narrow16IntOp     "narrow16Int#"     Monadic   Int# -> Int#
399 primop   Narrow32IntOp     "narrow32Int#"     Monadic   Int# -> Int#
400 primop   Narrow8WordOp     "narrow8Word#"     Monadic   Word# -> Word#
401 primop   Narrow16WordOp    "narrow16Word#"    Monadic   Word# -> Word#
402 primop   Narrow32WordOp    "narrow32Word#"    Monadic   Word# -> Word#
403
404
405 #if WORD_SIZE_IN_BITS < 32
406 ------------------------------------------------------------------------
407 section "Int32#"
408         {Operations on 32-bit integers ({\tt Int32\#}).  This type is only used
409          if plain {\tt Int\#} has less than 32 bits.  In any case, the operations
410          are not primops; they are implemented (if needed) as ccalls instead.}
411 ------------------------------------------------------------------------
412
413 primtype Int32#
414
415 ------------------------------------------------------------------------
416 section "Word32#"
417         {Operations on 32-bit unsigned words. This type is only used
418          if plain {\tt Word\#} has less than 32 bits. In any case, the operations
419          are not primops; they are implemented (if needed) as ccalls instead.}
420 ------------------------------------------------------------------------
421
422 primtype Word32#
423
424 #endif
425
426
427 #if WORD_SIZE_IN_BITS < 64
428 ------------------------------------------------------------------------
429 section "Int64#"
430         {Operations on 64-bit unsigned words. This type is only used
431          if plain {\tt Int\#} has less than 64 bits. In any case, the operations
432          are not primops; they are implemented (if needed) as ccalls instead.}
433 ------------------------------------------------------------------------
434
435 primtype Int64#
436
437 ------------------------------------------------------------------------
438 section "Word64#"
439         {Operations on 64-bit unsigned words. This type is only used
440          if plain {\tt Word\#} has less than 64 bits. In any case, the operations
441          are not primops; they are implemented (if needed) as ccalls instead.}
442 ------------------------------------------------------------------------
443
444 primtype Word64#
445
446 #endif
447
448 ------------------------------------------------------------------------
449 section "Double#"
450         {Operations on double-precision (64 bit) floating-point numbers.}
451 ------------------------------------------------------------------------
452
453 primtype Double#
454
455 primop   DoubleGtOp ">##"   Compare   Double# -> Double# -> Int#
456    with fixity = infix 4
457
458 primop   DoubleGeOp ">=##"   Compare   Double# -> Double# -> Int#
459    with fixity = infix 4
460
461 primop DoubleEqOp "==##"   Compare
462    Double# -> Double# -> Int#
463    with commutable = True
464         fixity = infix 4
465
466 primop DoubleNeOp "/=##"   Compare
467    Double# -> Double# -> Int#
468    with commutable = True
469         fixity = infix 4
470
471 primop   DoubleLtOp "<##"   Compare   Double# -> Double# -> Int#
472    with fixity = infix 4
473
474 primop   DoubleLeOp "<=##"   Compare   Double# -> Double# -> Int#
475    with fixity = infix 4
476
477 primop   DoubleAddOp   "+##"   Dyadic
478    Double# -> Double# -> Double#
479    with commutable = True
480         fixity = infixl 6
481
482 primop   DoubleSubOp   "-##"   Dyadic   Double# -> Double# -> Double#
483    with fixity = infixl 6
484
485 primop   DoubleMulOp   "*##"   Dyadic
486    Double# -> Double# -> Double#
487    with commutable = True
488         fixity = infixl 7
489
490 primop   DoubleDivOp   "/##"   Dyadic
491    Double# -> Double# -> Double#
492    with can_fail = True
493         fixity = infixl 7
494
495 primop   DoubleNegOp   "negateDouble#"  Monadic   Double# -> Double#
496
497 primop   Double2IntOp   "double2Int#"          GenPrimOp  Double# -> Int#
498    {Truncates a {\tt Double#} value to the nearest {\tt Int#}.
499     Results are undefined if the truncation if truncation yields
500     a value outside the range of {\tt Int#}.}
501
502 primop   Double2FloatOp   "double2Float#" GenPrimOp Double# -> Float#
503
504 primop   DoubleExpOp   "expDouble#"      Monadic
505    Double# -> Double#
506    with
507    code_size = { primOpCodeSizeForeignCall }
508
509 primop   DoubleLogOp   "logDouble#"      Monadic
510    Double# -> Double#
511    with
512    code_size = { primOpCodeSizeForeignCall }
513    can_fail = True
514
515 primop   DoubleSqrtOp   "sqrtDouble#"      Monadic
516    Double# -> Double#
517    with
518    code_size = { primOpCodeSizeForeignCall }
519
520 primop   DoubleSinOp   "sinDouble#"      Monadic
521    Double# -> Double#
522    with
523    code_size = { primOpCodeSizeForeignCall }
524
525 primop   DoubleCosOp   "cosDouble#"      Monadic
526    Double# -> Double#
527    with
528    code_size = { primOpCodeSizeForeignCall }
529
530 primop   DoubleTanOp   "tanDouble#"      Monadic
531    Double# -> Double#
532    with
533    code_size = { primOpCodeSizeForeignCall }
534
535 primop   DoubleAsinOp   "asinDouble#"      Monadic
536    Double# -> Double#
537    with
538    code_size = { primOpCodeSizeForeignCall }
539    can_fail = True
540
541 primop   DoubleAcosOp   "acosDouble#"      Monadic
542    Double# -> Double#
543    with
544    code_size = { primOpCodeSizeForeignCall }
545    can_fail = True
546
547 primop   DoubleAtanOp   "atanDouble#"      Monadic
548    Double# -> Double#
549    with
550    code_size = { primOpCodeSizeForeignCall }
551
552 primop   DoubleSinhOp   "sinhDouble#"      Monadic
553    Double# -> Double#
554    with
555    code_size = { primOpCodeSizeForeignCall }
556
557 primop   DoubleCoshOp   "coshDouble#"      Monadic
558    Double# -> Double#
559    with
560    code_size = { primOpCodeSizeForeignCall }
561
562 primop   DoubleTanhOp   "tanhDouble#"      Monadic
563    Double# -> Double#
564    with
565    code_size = { primOpCodeSizeForeignCall }
566
567 primop   DoublePowerOp   "**##" Dyadic
568    Double# -> Double# -> Double#
569    {Exponentiation.}
570    with
571    code_size = { primOpCodeSizeForeignCall }
572
573 primop   DoubleDecode_2IntOp   "decodeDouble_2Int#" GenPrimOp
574    Double# -> (# Int#, Word#, Word#, Int# #)
575    {Convert to integer.
576     First component of the result is -1 or 1, indicating the sign of the
577     mantissa. The next two are the high and low 32 bits of the mantissa
578     respectively, and the last is the exponent.}
579    with out_of_line = True
580
581 ------------------------------------------------------------------------
582 section "Float#"
583         {Operations on single-precision (32-bit) floating-point numbers.}
584 ------------------------------------------------------------------------
585
586 primtype Float#
587
588 primop   FloatGtOp  "gtFloat#"   Compare   Float# -> Float# -> Int#
589 primop   FloatGeOp  "geFloat#"   Compare   Float# -> Float# -> Int#
590
591 primop   FloatEqOp  "eqFloat#"   Compare
592    Float# -> Float# -> Int#
593    with commutable = True
594
595 primop   FloatNeOp  "neFloat#"   Compare
596    Float# -> Float# -> Int#
597    with commutable = True
598
599 primop   FloatLtOp  "ltFloat#"   Compare   Float# -> Float# -> Int#
600 primop   FloatLeOp  "leFloat#"   Compare   Float# -> Float# -> Int#
601
602 primop   FloatAddOp   "plusFloat#"      Dyadic
603    Float# -> Float# -> Float#
604    with commutable = True
605
606 primop   FloatSubOp   "minusFloat#"      Dyadic      Float# -> Float# -> Float#
607
608 primop   FloatMulOp   "timesFloat#"      Dyadic
609    Float# -> Float# -> Float#
610    with commutable = True
611
612 primop   FloatDivOp   "divideFloat#"      Dyadic
613    Float# -> Float# -> Float#
614    with can_fail = True
615
616 primop   FloatNegOp   "negateFloat#"      Monadic    Float# -> Float#
617
618 primop   Float2IntOp   "float2Int#"      GenPrimOp  Float# -> Int#
619    {Truncates a {\tt Float#} value to the nearest {\tt Int#}.
620     Results are undefined if the truncation if truncation yields
621     a value outside the range of {\tt Int#}.}
622
623 primop   FloatExpOp   "expFloat#"      Monadic
624    Float# -> Float#
625    with
626    code_size = { primOpCodeSizeForeignCall }
627
628 primop   FloatLogOp   "logFloat#"      Monadic
629    Float# -> Float#
630    with
631    code_size = { primOpCodeSizeForeignCall }
632    can_fail = True
633
634 primop   FloatSqrtOp   "sqrtFloat#"      Monadic
635    Float# -> Float#
636    with
637    code_size = { primOpCodeSizeForeignCall }
638
639 primop   FloatSinOp   "sinFloat#"      Monadic
640    Float# -> Float#
641    with
642    code_size = { primOpCodeSizeForeignCall }
643
644 primop   FloatCosOp   "cosFloat#"      Monadic
645    Float# -> Float#
646    with
647    code_size = { primOpCodeSizeForeignCall }
648
649 primop   FloatTanOp   "tanFloat#"      Monadic
650    Float# -> Float#
651    with
652    code_size = { primOpCodeSizeForeignCall }
653
654 primop   FloatAsinOp   "asinFloat#"      Monadic
655    Float# -> Float#
656    with
657    code_size = { primOpCodeSizeForeignCall }
658    can_fail = True
659
660 primop   FloatAcosOp   "acosFloat#"      Monadic
661    Float# -> Float#
662    with
663    code_size = { primOpCodeSizeForeignCall }
664    can_fail = True
665
666 primop   FloatAtanOp   "atanFloat#"      Monadic
667    Float# -> Float#
668    with
669    code_size = { primOpCodeSizeForeignCall }
670
671 primop   FloatSinhOp   "sinhFloat#"      Monadic
672    Float# -> Float#
673    with
674    code_size = { primOpCodeSizeForeignCall }
675
676 primop   FloatCoshOp   "coshFloat#"      Monadic
677    Float# -> Float#
678    with
679    code_size = { primOpCodeSizeForeignCall }
680
681 primop   FloatTanhOp   "tanhFloat#"      Monadic
682    Float# -> Float#
683    with
684    code_size = { primOpCodeSizeForeignCall }
685
686 primop   FloatPowerOp   "powerFloat#"      Dyadic
687    Float# -> Float# -> Float#
688    with
689    code_size = { primOpCodeSizeForeignCall }
690
691 primop   Float2DoubleOp   "float2Double#" GenPrimOp  Float# -> Double#
692
693 primop   FloatDecode_IntOp   "decodeFloat_Int#" GenPrimOp
694    Float# -> (# Int#, Int# #)
695    {Convert to integers.
696     First {\tt Int\#} in result is the mantissa; second is the exponent.}
697    with out_of_line = True
698
699 ------------------------------------------------------------------------
700 section "Arrays"
701         {Operations on {\tt Array\#}.}
702 ------------------------------------------------------------------------
703
704 primtype Array# a
705
706 primtype MutableArray# s a
707
708 primop  NewArrayOp "newArray#" GenPrimOp
709    Int# -> a -> State# s -> (# State# s, MutableArray# s a #)
710    {Create a new mutable array with the specified number of elements,
711     in the specified state thread,
712     with each element containing the specified initial value.}
713    with
714    out_of_line = True
715    has_side_effects = True
716
717 primop  SameMutableArrayOp "sameMutableArray#" GenPrimOp
718    MutableArray# s a -> MutableArray# s a -> Int#
719
720 primop  ReadArrayOp "readArray#" GenPrimOp
721    MutableArray# s a -> Int# -> State# s -> (# State# s, a #)
722    {Read from specified index of mutable array. Result is not yet evaluated.}
723    with
724    has_side_effects = True
725    can_fail         = True
726
727 primop  WriteArrayOp "writeArray#" GenPrimOp
728    MutableArray# s a -> Int# -> a -> State# s -> State# s
729    {Write to specified index of mutable array.}
730    with
731    has_side_effects = True
732    can_fail         = True
733    code_size        = 2 -- card update too
734
735 primop  SizeofArrayOp "sizeofArray#" GenPrimOp
736    Array# a -> Int#
737    {Return the number of elements in the array.}
738
739 primop  SizeofMutableArrayOp "sizeofMutableArray#" GenPrimOp
740    MutableArray# s a -> Int#
741    {Return the number of elements in the array.}
742
743 primop  IndexArrayOp "indexArray#" GenPrimOp
744    Array# a -> Int# -> (# a #)
745    {Read from specified index of immutable array. Result is packaged into
746     an unboxed singleton; the result itself is not yet evaluated.}
747    with
748    can_fail         = True
749
750 primop  UnsafeFreezeArrayOp "unsafeFreezeArray#" GenPrimOp
751    MutableArray# s a -> State# s -> (# State# s, Array# a #)
752    {Make a mutable array immutable, without copying.}
753    with
754    has_side_effects = True
755
756 primop  UnsafeThawArrayOp  "unsafeThawArray#" GenPrimOp
757    Array# a -> State# s -> (# State# s, MutableArray# s a #)
758    {Make an immutable array mutable, without copying.}
759    with
760    out_of_line = True
761    has_side_effects = True
762
763 primop  CopyArrayOp "copyArray#" GenPrimOp
764   Array# a -> Int# -> MutableArray# s a -> Int# -> Int# -> State# s -> State# s
765   {Given a source array, an offset into the source array, a
766    destination array, an offset into the destination array, and a
767    number of elements to copy, copy the elements from the source array
768    to the destination array. Both arrays must fully contain the
769    specified ranges, but this is not checked. The two arrays must not
770    be the same array in different states, but this is not checked
771    either.}
772   with
773   has_side_effects = True
774   can_fail         = True
775   code_size = { primOpCodeSizeForeignCall + 4 }
776
777 primop  CopyMutableArrayOp "copyMutableArray#" GenPrimOp
778   MutableArray# s a -> Int# -> MutableArray# s a -> Int# -> Int# -> State# s -> State# s
779   {Given a source array, an offset into the source array, a
780    destination array, an offset into the destination array, and a
781    number of elements to copy, copy the elements from the source array
782    to the destination array. The source and destination arrays can
783    refer to the same array. Both arrays must fully contain the
784    specified ranges, but this is not checked.}
785   with
786   has_side_effects = True
787   can_fail         = True
788   code_size = { primOpCodeSizeForeignCall + 4 }
789
790 primop  CloneArrayOp "cloneArray#" GenPrimOp
791   Array# a -> Int# -> Int# -> Array# a
792   {Given a source array, an offset into the source array, and a number
793    of elements to copy, create a new array with the elements from the
794    source array. The provided array must fully contain the specified
795    range, but this is not checked.}
796   with
797   out_of_line      = True
798   has_side_effects = True
799   code_size = { primOpCodeSizeForeignCall + 4 }
800
801 primop  CloneMutableArrayOp "cloneMutableArray#" GenPrimOp
802   MutableArray# s a -> Int# -> Int# -> State# s -> (# State# s, MutableArray# s a #)
803   {Given a source array, an offset into the source array, and a number
804    of elements to copy, create a new array with the elements from the
805    source array. The provided array must fully contain the specified
806    range, but this is not checked.}
807   with
808   out_of_line      = True
809   has_side_effects = True
810   code_size = { primOpCodeSizeForeignCall + 4 }
811
812 primop  FreezeArrayOp "freezeArray#" GenPrimOp
813   MutableArray# s a -> Int# -> Int# -> State# s -> (# State# s, Array# a #)
814   {Given a source array, an offset into the source array, and a number
815    of elements to copy, create a new array with the elements from the
816    source array. The provided array must fully contain the specified
817    range, but this is not checked.}
818   with
819   out_of_line      = True
820   has_side_effects = True
821   code_size = { primOpCodeSizeForeignCall + 4 }
822
823 primop  ThawArrayOp "thawArray#" GenPrimOp
824   Array# a -> Int# -> Int# -> State# s -> (# State# s, MutableArray# s a #)
825   {Given a source array, an offset into the source array, and a number
826    of elements to copy, create a new array with the elements from the
827    source array. The provided array must fully contain the specified
828    range, but this is not checked.}
829   with
830   out_of_line      = True
831   has_side_effects = True
832   code_size = { primOpCodeSizeForeignCall + 4 }
833
834 primop CasArrayOp  "casArray#" GenPrimOp
835    MutableArray# s a -> Int# -> a -> a -> State# s -> (# State# s, Int#, a #)
836    {Unsafe, machine-level atomic compare and swap on an element within an Array.}
837    with
838    out_of_line = True
839    has_side_effects = True
840
841
842 ------------------------------------------------------------------------
843 section "Byte Arrays"
844         {Operations on {\tt ByteArray\#}. A {\tt ByteArray\#} is a just a region of
845          raw memory in the garbage-collected heap, which is not
846          scanned for pointers. It carries its own size (in bytes).
847          There are
848          three sets of operations for accessing byte array contents:
849          index for reading from immutable byte arrays, and read/write
850          for mutable byte arrays.  Each set contains operations for a
851          range of useful primitive data types.  Each operation takes
852          an offset measured in terms of the size of the primitive type
853          being read or written.}
854
855 ------------------------------------------------------------------------
856
857 primtype ByteArray#
858
859 primtype MutableByteArray# s
860
861 primop  NewByteArrayOp_Char "newByteArray#" GenPrimOp
862    Int# -> State# s -> (# State# s, MutableByteArray# s #)
863    {Create a new mutable byte array of specified size (in bytes), in
864     the specified state thread.}
865    with out_of_line = True
866         has_side_effects = True
867
868 primop  NewPinnedByteArrayOp_Char "newPinnedByteArray#" GenPrimOp
869    Int# -> State# s -> (# State# s, MutableByteArray# s #)
870    {Create a mutable byte array that the GC guarantees not to move.}
871    with out_of_line = True
872         has_side_effects = True
873
874 primop  NewAlignedPinnedByteArrayOp_Char "newAlignedPinnedByteArray#" GenPrimOp
875    Int# -> Int# -> State# s -> (# State# s, MutableByteArray# s #)
876    {Create a mutable byte array, aligned by the specified amount, that the GC guarantees not to move.}
877    with out_of_line = True
878         has_side_effects = True
879
880 primop  ByteArrayContents_Char "byteArrayContents#" GenPrimOp
881    ByteArray# -> Addr#
882    {Intended for use with pinned arrays; otherwise very unsafe!}
883
884 primop  SameMutableByteArrayOp "sameMutableByteArray#" GenPrimOp
885    MutableByteArray# s -> MutableByteArray# s -> Int#
886
887 primop  UnsafeFreezeByteArrayOp "unsafeFreezeByteArray#" GenPrimOp
888    MutableByteArray# s -> State# s -> (# State# s, ByteArray# #)
889    {Make a mutable byte array immutable, without copying.}
890    with
891    has_side_effects = True
892
893 primop  SizeofByteArrayOp "sizeofByteArray#" GenPrimOp
894    ByteArray# -> Int#
895    {Return the size of the array in bytes.}
896
897 primop  SizeofMutableByteArrayOp "sizeofMutableByteArray#" GenPrimOp
898    MutableByteArray# s -> Int#
899    {Return the size of the array in bytes.}
900
901 primop IndexByteArrayOp_Char "indexCharArray#" GenPrimOp
902    ByteArray# -> Int# -> Char#
903    {Read 8-bit character; offset in bytes.}
904    with can_fail = True
905
906 primop IndexByteArrayOp_WideChar "indexWideCharArray#" GenPrimOp
907    ByteArray# -> Int# -> Char#
908    {Read 31-bit character; offset in 4-byte words.}
909    with can_fail = True
910
911 primop IndexByteArrayOp_Int "indexIntArray#" GenPrimOp
912    ByteArray# -> Int# -> Int#
913    with can_fail = True
914
915 primop IndexByteArrayOp_Word "indexWordArray#" GenPrimOp
916    ByteArray# -> Int# -> Word#
917    with can_fail = True
918
919 primop IndexByteArrayOp_Addr "indexAddrArray#" GenPrimOp
920    ByteArray# -> Int# -> Addr#
921    with can_fail = True
922
923 primop IndexByteArrayOp_Float "indexFloatArray#" GenPrimOp
924    ByteArray# -> Int# -> Float#
925    with can_fail = True
926
927 primop IndexByteArrayOp_Double "indexDoubleArray#" GenPrimOp
928    ByteArray# -> Int# -> Double#
929    with can_fail = True
930
931 primop IndexByteArrayOp_StablePtr "indexStablePtrArray#" GenPrimOp
932    ByteArray# -> Int# -> StablePtr# a
933    with can_fail = True
934
935 primop IndexByteArrayOp_Int8 "indexInt8Array#" GenPrimOp
936    ByteArray# -> Int# -> Int#
937    with can_fail = True
938
939 primop IndexByteArrayOp_Int16 "indexInt16Array#" GenPrimOp
940    ByteArray# -> Int# -> Int#
941    with can_fail = True
942
943 primop IndexByteArrayOp_Int32 "indexInt32Array#" GenPrimOp
944    ByteArray# -> Int# -> INT32
945    with can_fail = True
946
947 primop IndexByteArrayOp_Int64 "indexInt64Array#" GenPrimOp
948    ByteArray# -> Int# -> INT64
949    with can_fail = True
950
951 primop IndexByteArrayOp_Word8 "indexWord8Array#" GenPrimOp
952    ByteArray# -> Int# -> Word#
953    with can_fail = True
954
955 primop IndexByteArrayOp_Word16 "indexWord16Array#" GenPrimOp
956    ByteArray# -> Int# -> Word#
957    with can_fail = True
958
959 primop IndexByteArrayOp_Word32 "indexWord32Array#" GenPrimOp
960    ByteArray# -> Int# -> WORD32
961    with can_fail = True
962
963 primop IndexByteArrayOp_Word64 "indexWord64Array#" GenPrimOp
964    ByteArray# -> Int# -> WORD64
965    with can_fail = True
966
967 primop  ReadByteArrayOp_Char "readCharArray#" GenPrimOp
968    MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
969    {Read 8-bit character; offset in bytes.}
970    with has_side_effects = True
971         can_fail = True
972
973 primop  ReadByteArrayOp_WideChar "readWideCharArray#" GenPrimOp
974    MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
975    {Read 31-bit character; offset in 4-byte words.}
976    with has_side_effects = True
977         can_fail = True
978
979 primop  ReadByteArrayOp_Int "readIntArray#" GenPrimOp
980    MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
981    with has_side_effects = True
982         can_fail = True
983
984 primop  ReadByteArrayOp_Word "readWordArray#" GenPrimOp
985    MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
986    with has_side_effects = True
987         can_fail = True
988
989 primop  ReadByteArrayOp_Addr "readAddrArray#" GenPrimOp
990    MutableByteArray# s -> Int# -> State# s -> (# State# s, Addr# #)
991    with has_side_effects = True
992         can_fail = True
993
994 primop  ReadByteArrayOp_Float "readFloatArray#" GenPrimOp
995    MutableByteArray# s -> Int# -> State# s -> (# State# s, Float# #)
996    with has_side_effects = True
997         can_fail = True
998
999 primop  ReadByteArrayOp_Double "readDoubleArray#" GenPrimOp
1000    MutableByteArray# s -> Int# -> State# s -> (# State# s, Double# #)
1001    with has_side_effects = True
1002         can_fail = True
1003
1004 primop  ReadByteArrayOp_StablePtr "readStablePtrArray#" GenPrimOp
1005    MutableByteArray# s -> Int# -> State# s -> (# State# s, StablePtr# a #)
1006    with has_side_effects = True
1007         can_fail = True
1008
1009 primop  ReadByteArrayOp_Int8 "readInt8Array#" GenPrimOp
1010    MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
1011    with has_side_effects = True
1012         can_fail = True
1013
1014 primop  ReadByteArrayOp_Int16 "readInt16Array#" GenPrimOp
1015    MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
1016    with has_side_effects = True
1017         can_fail = True
1018
1019 primop  ReadByteArrayOp_Int32 "readInt32Array#" GenPrimOp
1020    MutableByteArray# s -> Int# -> State# s -> (# State# s, INT32 #)
1021    with has_side_effects = True
1022         can_fail = True
1023
1024 primop  ReadByteArrayOp_Int64 "readInt64Array#" GenPrimOp
1025    MutableByteArray# s -> Int# -> State# s -> (# State# s, INT64 #)
1026    with has_side_effects = True
1027         can_fail = True
1028
1029 primop  ReadByteArrayOp_Word8 "readWord8Array#" GenPrimOp
1030    MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
1031    with has_side_effects = True
1032         can_fail = True
1033
1034 primop  ReadByteArrayOp_Word16 "readWord16Array#" GenPrimOp
1035    MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
1036    with has_side_effects = True
1037         can_fail = True
1038
1039 primop  ReadByteArrayOp_Word32 "readWord32Array#" GenPrimOp
1040    MutableByteArray# s -> Int# -> State# s -> (# State# s, WORD32 #)
1041    with has_side_effects = True
1042         can_fail = True
1043
1044 primop  ReadByteArrayOp_Word64 "readWord64Array#" GenPrimOp
1045    MutableByteArray# s -> Int# -> State# s -> (# State# s, WORD64 #)
1046    with has_side_effects = True
1047         can_fail = True
1048
1049 primop  WriteByteArrayOp_Char "writeCharArray#" GenPrimOp
1050    MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
1051    {Write 8-bit character; offset in bytes.}
1052    with has_side_effects = True
1053         can_fail = True
1054
1055 primop  WriteByteArrayOp_WideChar "writeWideCharArray#" GenPrimOp
1056    MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
1057    {Write 31-bit character; offset in 4-byte words.}
1058    with has_side_effects = True
1059         can_fail = True
1060
1061 primop  WriteByteArrayOp_Int "writeIntArray#" GenPrimOp
1062    MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1063    with has_side_effects = True
1064         can_fail = True
1065
1066 primop  WriteByteArrayOp_Word "writeWordArray#" GenPrimOp
1067    MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
1068    with has_side_effects = True
1069         can_fail = True
1070
1071 primop  WriteByteArrayOp_Addr "writeAddrArray#" GenPrimOp
1072    MutableByteArray# s -> Int# -> Addr# -> State# s -> State# s
1073    with has_side_effects = True
1074         can_fail = True
1075
1076 primop  WriteByteArrayOp_Float "writeFloatArray#" GenPrimOp
1077    MutableByteArray# s -> Int# -> Float# -> State# s -> State# s
1078    with has_side_effects = True
1079         can_fail = True
1080
1081 primop  WriteByteArrayOp_Double "writeDoubleArray#" GenPrimOp
1082    MutableByteArray# s -> Int# -> Double# -> State# s -> State# s
1083    with has_side_effects = True
1084         can_fail = True
1085
1086 primop  WriteByteArrayOp_StablePtr "writeStablePtrArray#" GenPrimOp
1087    MutableByteArray# s -> Int# -> StablePtr# a -> State# s -> State# s
1088    with has_side_effects = True
1089         can_fail = True
1090
1091 primop  WriteByteArrayOp_Int8 "writeInt8Array#" GenPrimOp
1092    MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1093    with has_side_effects = True
1094         can_fail = True
1095
1096 primop  WriteByteArrayOp_Int16 "writeInt16Array#" GenPrimOp
1097    MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1098    with has_side_effects = True
1099         can_fail = True
1100
1101 primop  WriteByteArrayOp_Int32 "writeInt32Array#" GenPrimOp
1102    MutableByteArray# s -> Int# -> INT32 -> State# s -> State# s
1103    with has_side_effects = True
1104         can_fail = True
1105
1106 primop  WriteByteArrayOp_Int64 "writeInt64Array#" GenPrimOp
1107    MutableByteArray# s -> Int# -> INT64 -> State# s -> State# s
1108    with can_fail = True
1109         has_side_effects = True
1110
1111 primop  WriteByteArrayOp_Word8 "writeWord8Array#" GenPrimOp
1112    MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
1113    with has_side_effects = True
1114         can_fail = True
1115
1116 primop  WriteByteArrayOp_Word16 "writeWord16Array#" GenPrimOp
1117    MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
1118    with has_side_effects = True
1119         can_fail = True
1120
1121 primop  WriteByteArrayOp_Word32 "writeWord32Array#" GenPrimOp
1122    MutableByteArray# s -> Int# -> WORD32 -> State# s -> State# s
1123    with has_side_effects = True
1124         can_fail = True
1125
1126 primop  WriteByteArrayOp_Word64 "writeWord64Array#" GenPrimOp
1127    MutableByteArray# s -> Int# -> WORD64 -> State# s -> State# s
1128    with has_side_effects = True
1129         can_fail = True
1130
1131 primop  CopyByteArrayOp "copyByteArray#" GenPrimOp
1132   ByteArray# -> Int# -> MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1133   {Copy a range of the ByteArray# to the specified region in the MutableByteArray#.
1134    Both arrays must fully contain the specified ranges, but this is not checked.
1135    The two arrays must not be the same array in different states, but this is not checked either.}
1136   with
1137   has_side_effects = True
1138   code_size = { primOpCodeSizeForeignCall + 4}
1139   can_fail = True
1140
1141 primop  CopyMutableByteArrayOp "copyMutableByteArray#" GenPrimOp
1142   MutableByteArray# s -> Int# -> MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1143   {Copy a range of the first MutableByteArray# to the specified region in the second MutableByteArray#.
1144    Both arrays must fully contain the specified ranges, but this is not checked.}
1145   with
1146   has_side_effects = True
1147   code_size = { primOpCodeSizeForeignCall + 4 }
1148   can_fail = True
1149
1150 primop  CopyByteArrayToAddrOp "copyByteArrayToAddr#" GenPrimOp
1151   ByteArray# -> Int# -> Addr# -> Int# -> State# s -> State# s
1152   {Copy a range of the ByteArray# to the memory range starting at the Addr#.
1153    The ByteArray# and the memory region at Addr# must fully contain the
1154    specified ranges, but this is not checked. The Addr# must not point into the
1155    ByteArray# (e.g. if the ByteArray# were pinned), but this is not checked
1156    either.}
1157   with
1158   has_side_effects = True
1159   code_size = { primOpCodeSizeForeignCall + 4}
1160   can_fail = True
1161
1162 primop  CopyMutableByteArrayToAddrOp "copyMutableByteArrayToAddr#" GenPrimOp
1163   MutableByteArray# s -> Int# -> Addr# -> Int# -> State# s -> State# s
1164   {Copy a range of the MutableByteArray# to the memory range starting at the
1165    Addr#. The MutableByteArray# and the memory region at Addr# must fully
1166    contain the specified ranges, but this is not checked. The Addr# must not
1167    point into the MutableByteArray# (e.g. if the MutableByteArray# were
1168    pinned), but this is not checked either.}
1169   with
1170   has_side_effects = True
1171   code_size = { primOpCodeSizeForeignCall + 4}
1172   can_fail = True
1173
1174 primop  CopyAddrToByteArrayOp "copyAddrToByteArray#" GenPrimOp
1175   Addr# -> MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1176   {Copy a memory range starting at the Addr# to the specified range in the
1177    MutableByteArray#. The memory region at Addr# and the ByteArray# must fully
1178    contain the specified ranges, but this is not checked. The Addr# must not
1179    point into the MutableByteArray# (e.g. if the MutableByteArray# were pinned),
1180    but this is not checked either.}
1181   with
1182   has_side_effects = True
1183   code_size = { primOpCodeSizeForeignCall + 4}
1184   can_fail = True
1185
1186 primop  SetByteArrayOp "setByteArray#" GenPrimOp
1187   MutableByteArray# s -> Int# -> Int# -> Int# -> State# s -> State# s
1188   {Set the range of the MutableByteArray# to the specified character.}
1189   with
1190   has_side_effects = True
1191   code_size = { primOpCodeSizeForeignCall + 4 }
1192   can_fail = True
1193
1194 primop CasByteArrayOp_Int "casIntArray#" GenPrimOp
1195    MutableByteArray# s -> Int# -> Int# -> Int# -> State# s -> (# State# s, Int# #)
1196    {Machine-level atomic compare and swap on a word within a ByteArray.}
1197    with
1198    out_of_line = True
1199    has_side_effects = True
1200
1201 primop FetchAddByteArrayOp_Int "fetchAddIntArray#" GenPrimOp
1202    MutableByteArray# s -> Int# -> Int# -> State# s -> (# State# s, Int# #)
1203    {Machine-level word-sized fetch-and-add within a ByteArray.}
1204    with
1205    out_of_line = True
1206    has_side_effects = True
1207
1208
1209 ------------------------------------------------------------------------
1210 section "Arrays of arrays"
1211         {Operations on {\tt ArrayArray\#}. An {\tt ArrayArray\#} contains references to {\em unpointed}
1212          arrays, such as {\tt ByteArray\#s}. Hence, it is not parameterised by the element types,
1213          just like a {\tt ByteArray\#}, but it needs to be scanned during GC, just like an {\tt Array#}.
1214          We represent an {\tt ArrayArray\#} exactly as a {\tt Array\#}, but provide element-type-specific
1215          indexing, reading, and writing.}
1216 ------------------------------------------------------------------------
1217
1218 primtype ArrayArray#
1219
1220 primtype MutableArrayArray# s
1221
1222 primop  NewArrayArrayOp "newArrayArray#" GenPrimOp
1223    Int# -> State# s -> (# State# s, MutableArrayArray# s #)
1224    {Create a new mutable array of arrays with the specified number of elements,
1225     in the specified state thread, with each element recursively referring to the
1226     newly created array.}
1227    with
1228    out_of_line = True
1229    has_side_effects = True
1230
1231 primop  SameMutableArrayArrayOp "sameMutableArrayArray#" GenPrimOp
1232    MutableArrayArray# s -> MutableArrayArray# s -> Int#
1233
1234 primop  UnsafeFreezeArrayArrayOp "unsafeFreezeArrayArray#" GenPrimOp
1235    MutableArrayArray# s -> State# s -> (# State# s, ArrayArray# #)
1236    {Make a mutable array of arrays immutable, without copying.}
1237    with
1238    has_side_effects = True
1239
1240 primop  SizeofArrayArrayOp "sizeofArrayArray#" GenPrimOp
1241    ArrayArray# -> Int#
1242    {Return the number of elements in the array.}
1243
1244 primop  SizeofMutableArrayArrayOp "sizeofMutableArrayArray#" GenPrimOp
1245    MutableArrayArray# s -> Int#
1246    {Return the number of elements in the array.}
1247
1248 primop IndexArrayArrayOp_ByteArray "indexByteArrayArray#" GenPrimOp
1249    ArrayArray# -> Int# -> ByteArray#
1250    with can_fail = True
1251
1252 primop IndexArrayArrayOp_ArrayArray "indexArrayArrayArray#" GenPrimOp
1253    ArrayArray# -> Int# -> ArrayArray#
1254    with can_fail = True
1255
1256 primop  ReadArrayArrayOp_ByteArray "readByteArrayArray#" GenPrimOp
1257    MutableArrayArray# s -> Int# -> State# s -> (# State# s, ByteArray# #)
1258    with has_side_effects = True
1259         can_fail = True
1260
1261 primop  ReadArrayArrayOp_MutableByteArray "readMutableByteArrayArray#" GenPrimOp
1262    MutableArrayArray# s -> Int# -> State# s -> (# State# s, MutableByteArray# s #)
1263    with has_side_effects = True
1264         can_fail = True
1265
1266 primop  ReadArrayArrayOp_ArrayArray "readArrayArrayArray#" GenPrimOp
1267    MutableArrayArray# s -> Int# -> State# s -> (# State# s, ArrayArray# #)
1268    with has_side_effects = True
1269         can_fail = True
1270
1271 primop  ReadArrayArrayOp_MutableArrayArray "readMutableArrayArrayArray#" GenPrimOp
1272    MutableArrayArray# s -> Int# -> State# s -> (# State# s, MutableArrayArray# s #)
1273    with has_side_effects = True
1274         can_fail = True
1275
1276 primop  WriteArrayArrayOp_ByteArray "writeByteArrayArray#" GenPrimOp
1277    MutableArrayArray# s -> Int# -> ByteArray# -> State# s -> State# s
1278    with has_side_effects = True
1279         can_fail = True
1280
1281 primop  WriteArrayArrayOp_MutableByteArray "writeMutableByteArrayArray#" GenPrimOp
1282    MutableArrayArray# s -> Int# -> MutableByteArray# s -> State# s -> State# s
1283    with has_side_effects = True
1284         can_fail = True
1285
1286 primop  WriteArrayArrayOp_ArrayArray "writeArrayArrayArray#" GenPrimOp
1287    MutableArrayArray# s -> Int# -> ArrayArray# -> State# s -> State# s
1288    with has_side_effects = True
1289         can_fail = True
1290
1291 primop  WriteArrayArrayOp_MutableArrayArray "writeMutableArrayArrayArray#" GenPrimOp
1292    MutableArrayArray# s -> Int# -> MutableArrayArray# s -> State# s -> State# s
1293    with has_side_effects = True
1294         can_fail = True
1295
1296 primop  CopyArrayArrayOp "copyArrayArray#" GenPrimOp
1297   ArrayArray# -> Int# -> MutableArrayArray# s -> Int# -> Int# -> State# s -> State# s
1298   {Copy a range of the ArrayArray# to the specified region in the MutableArrayArray#.
1299    Both arrays must fully contain the specified ranges, but this is not checked.
1300    The two arrays must not be the same array in different states, but this is not checked either.}
1301   with
1302   has_side_effects = True
1303   can_fail = True
1304   code_size = { primOpCodeSizeForeignCall }
1305
1306 primop  CopyMutableArrayArrayOp "copyMutableArrayArray#" GenPrimOp
1307   MutableArrayArray# s -> Int# -> MutableArrayArray# s -> Int# -> Int# -> State# s -> State# s
1308   {Copy a range of the first MutableArrayArray# to the specified region in the second
1309    MutableArrayArray#.
1310    Both arrays must fully contain the specified ranges, but this is not checked.}
1311   with
1312   has_side_effects = True
1313   code_size = { primOpCodeSizeForeignCall }
1314   can_fail = True
1315
1316 ------------------------------------------------------------------------
1317 section "Addr#"
1318 ------------------------------------------------------------------------
1319
1320 primtype Addr#
1321         { An arbitrary machine address assumed to point outside
1322          the garbage-collected heap. }
1323
1324 pseudoop "nullAddr#" Addr#
1325         { The null address. }
1326
1327 primop   AddrAddOp "plusAddr#" GenPrimOp Addr# -> Int# -> Addr#
1328 primop   AddrSubOp "minusAddr#" GenPrimOp Addr# -> Addr# -> Int#
1329          {Result is meaningless if two {\tt Addr\#}s are so far apart that their
1330          difference doesn't fit in an {\tt Int\#}.}
1331 primop   AddrRemOp "remAddr#" GenPrimOp Addr# -> Int# -> Int#
1332          {Return the remainder when the {\tt Addr\#} arg, treated like an {\tt Int\#},
1333           is divided by the {\tt Int\#} arg.}
1334 #if (WORD_SIZE_IN_BITS == 32 || WORD_SIZE_IN_BITS == 64)
1335 primop   Addr2IntOp  "addr2Int#"     GenPrimOp   Addr# -> Int#
1336         {Coerce directly from address to int. Strongly deprecated.}
1337    with code_size = 0
1338 primop   Int2AddrOp   "int2Addr#"    GenPrimOp  Int# -> Addr#
1339         {Coerce directly from int to address. Strongly deprecated.}
1340    with code_size = 0
1341 #endif
1342
1343 primop   AddrGtOp  "gtAddr#"   Compare   Addr# -> Addr# -> Int#
1344 primop   AddrGeOp  "geAddr#"   Compare   Addr# -> Addr# -> Int#
1345 primop   AddrEqOp  "eqAddr#"   Compare   Addr# -> Addr# -> Int#
1346 primop   AddrNeOp  "neAddr#"   Compare   Addr# -> Addr# -> Int#
1347 primop   AddrLtOp  "ltAddr#"   Compare   Addr# -> Addr# -> Int#
1348 primop   AddrLeOp  "leAddr#"   Compare   Addr# -> Addr# -> Int#
1349
1350 primop IndexOffAddrOp_Char "indexCharOffAddr#" GenPrimOp
1351    Addr# -> Int# -> Char#
1352    {Reads 8-bit character; offset in bytes.}
1353    with can_fail = True
1354
1355 primop IndexOffAddrOp_WideChar "indexWideCharOffAddr#" GenPrimOp
1356    Addr# -> Int# -> Char#
1357    {Reads 31-bit character; offset in 4-byte words.}
1358    with can_fail = True
1359
1360 primop IndexOffAddrOp_Int "indexIntOffAddr#" GenPrimOp
1361    Addr# -> Int# -> Int#
1362    with can_fail = True
1363
1364 primop IndexOffAddrOp_Word "indexWordOffAddr#" GenPrimOp
1365    Addr# -> Int# -> Word#
1366    with can_fail = True
1367
1368 primop IndexOffAddrOp_Addr "indexAddrOffAddr#" GenPrimOp
1369    Addr# -> Int# -> Addr#
1370    with can_fail = True
1371
1372 primop IndexOffAddrOp_Float "indexFloatOffAddr#" GenPrimOp
1373    Addr# -> Int# -> Float#
1374    with can_fail = True
1375
1376 primop IndexOffAddrOp_Double "indexDoubleOffAddr#" GenPrimOp
1377    Addr# -> Int# -> Double#
1378    with can_fail = True
1379
1380 primop IndexOffAddrOp_StablePtr "indexStablePtrOffAddr#" GenPrimOp
1381    Addr# -> Int# -> StablePtr# a
1382    with can_fail = True
1383
1384 primop IndexOffAddrOp_Int8 "indexInt8OffAddr#" GenPrimOp
1385    Addr# -> Int# -> Int#
1386    with can_fail = True
1387
1388 primop IndexOffAddrOp_Int16 "indexInt16OffAddr#" GenPrimOp
1389    Addr# -> Int# -> Int#
1390    with can_fail = True
1391
1392 primop IndexOffAddrOp_Int32 "indexInt32OffAddr#" GenPrimOp
1393    Addr# -> Int# -> INT32
1394    with can_fail = True
1395
1396 primop IndexOffAddrOp_Int64 "indexInt64OffAddr#" GenPrimOp
1397    Addr# -> Int# -> INT64
1398    with can_fail = True
1399
1400 primop IndexOffAddrOp_Word8 "indexWord8OffAddr#" GenPrimOp
1401    Addr# -> Int# -> Word#
1402    with can_fail = True
1403
1404 primop IndexOffAddrOp_Word16 "indexWord16OffAddr#" GenPrimOp
1405    Addr# -> Int# -> Word#
1406    with can_fail = True
1407
1408 primop IndexOffAddrOp_Word32 "indexWord32OffAddr#" GenPrimOp
1409    Addr# -> Int# -> WORD32
1410    with can_fail = True
1411
1412 primop IndexOffAddrOp_Word64 "indexWord64OffAddr#" GenPrimOp
1413    Addr# -> Int# -> WORD64
1414    with can_fail = True
1415
1416 primop ReadOffAddrOp_Char "readCharOffAddr#" GenPrimOp
1417    Addr# -> Int# -> State# s -> (# State# s, Char# #)
1418    {Reads 8-bit character; offset in bytes.}
1419    with has_side_effects = True
1420         can_fail         = True
1421
1422 primop ReadOffAddrOp_WideChar "readWideCharOffAddr#" GenPrimOp
1423    Addr# -> Int# -> State# s -> (# State# s, Char# #)
1424    {Reads 31-bit character; offset in 4-byte words.}
1425    with has_side_effects = True
1426         can_fail         = True
1427
1428 primop ReadOffAddrOp_Int "readIntOffAddr#" GenPrimOp
1429    Addr# -> Int# -> State# s -> (# State# s, Int# #)
1430    with has_side_effects = True
1431         can_fail         = True
1432
1433 primop ReadOffAddrOp_Word "readWordOffAddr#" GenPrimOp
1434    Addr# -> Int# -> State# s -> (# State# s, Word# #)
1435    with has_side_effects = True
1436         can_fail         = True
1437
1438 primop ReadOffAddrOp_Addr "readAddrOffAddr#" GenPrimOp
1439    Addr# -> Int# -> State# s -> (# State# s, Addr# #)
1440    with has_side_effects = True
1441         can_fail         = True
1442
1443 primop ReadOffAddrOp_Float "readFloatOffAddr#" GenPrimOp
1444    Addr# -> Int# -> State# s -> (# State# s, Float# #)
1445    with has_side_effects = True
1446         can_fail         = True
1447
1448 primop ReadOffAddrOp_Double "readDoubleOffAddr#" GenPrimOp
1449    Addr# -> Int# -> State# s -> (# State# s, Double# #)
1450    with has_side_effects = True
1451         can_fail         = True
1452
1453 primop ReadOffAddrOp_StablePtr "readStablePtrOffAddr#" GenPrimOp
1454    Addr# -> Int# -> State# s -> (# State# s, StablePtr# a #)
1455    with has_side_effects = True
1456         can_fail         = True
1457
1458 primop ReadOffAddrOp_Int8 "readInt8OffAddr#" GenPrimOp
1459    Addr# -> Int# -> State# s -> (# State# s, Int# #)
1460    with has_side_effects = True
1461         can_fail         = True
1462
1463 primop ReadOffAddrOp_Int16 "readInt16OffAddr#" GenPrimOp
1464    Addr# -> Int# -> State# s -> (# State# s, Int# #)
1465    with has_side_effects = True
1466         can_fail         = True
1467
1468 primop ReadOffAddrOp_Int32 "readInt32OffAddr#" GenPrimOp
1469    Addr# -> Int# -> State# s -> (# State# s, INT32 #)
1470    with has_side_effects = True
1471         can_fail         = True
1472
1473 primop ReadOffAddrOp_Int64 "readInt64OffAddr#" GenPrimOp
1474    Addr# -> Int# -> State# s -> (# State# s, INT64 #)
1475    with has_side_effects = True
1476         can_fail         = True
1477
1478 primop ReadOffAddrOp_Word8 "readWord8OffAddr#" GenPrimOp
1479    Addr# -> Int# -> State# s -> (# State# s, Word# #)
1480    with has_side_effects = True
1481         can_fail         = True
1482
1483 primop ReadOffAddrOp_Word16 "readWord16OffAddr#" GenPrimOp
1484    Addr# -> Int# -> State# s -> (# State# s, Word# #)
1485    with has_side_effects = True
1486         can_fail         = True
1487
1488 primop ReadOffAddrOp_Word32 "readWord32OffAddr#" GenPrimOp
1489    Addr# -> Int# -> State# s -> (# State# s, WORD32 #)
1490    with has_side_effects = True
1491         can_fail         = True
1492
1493 primop ReadOffAddrOp_Word64 "readWord64OffAddr#" GenPrimOp
1494    Addr# -> Int# -> State# s -> (# State# s, WORD64 #)
1495    with has_side_effects = True
1496         can_fail         = True
1497
1498 primop  WriteOffAddrOp_Char "writeCharOffAddr#" GenPrimOp
1499    Addr# -> Int# -> Char# -> State# s -> State# s
1500    with has_side_effects = True
1501         can_fail         = True
1502
1503 primop  WriteOffAddrOp_WideChar "writeWideCharOffAddr#" GenPrimOp
1504    Addr# -> Int# -> Char# -> State# s -> State# s
1505    with has_side_effects = True
1506         can_fail         = True
1507
1508 primop  WriteOffAddrOp_Int "writeIntOffAddr#" GenPrimOp
1509    Addr# -> Int# -> Int# -> State# s -> State# s
1510    with has_side_effects = True
1511         can_fail         = True
1512
1513 primop  WriteOffAddrOp_Word "writeWordOffAddr#" GenPrimOp
1514    Addr# -> Int# -> Word# -> State# s -> State# s
1515    with has_side_effects = True
1516         can_fail         = True
1517
1518 primop  WriteOffAddrOp_Addr "writeAddrOffAddr#" GenPrimOp
1519    Addr# -> Int# -> Addr# -> State# s -> State# s
1520    with has_side_effects = True
1521         can_fail         = True
1522
1523 primop  WriteOffAddrOp_Float "writeFloatOffAddr#" GenPrimOp
1524    Addr# -> Int# -> Float# -> State# s -> State# s
1525    with has_side_effects = True
1526         can_fail         = True
1527
1528 primop  WriteOffAddrOp_Double "writeDoubleOffAddr#" GenPrimOp
1529    Addr# -> Int# -> Double# -> State# s -> State# s
1530    with has_side_effects = True
1531         can_fail         = True
1532
1533 primop  WriteOffAddrOp_StablePtr "writeStablePtrOffAddr#" GenPrimOp
1534    Addr# -> Int# -> StablePtr# a -> State# s -> State# s
1535    with has_side_effects = True
1536         can_fail         = True
1537
1538 primop  WriteOffAddrOp_Int8 "writeInt8OffAddr#" GenPrimOp
1539    Addr# -> Int# -> Int# -> State# s -> State# s
1540    with has_side_effects = True
1541         can_fail         = True
1542
1543 primop  WriteOffAddrOp_Int16 "writeInt16OffAddr#" GenPrimOp
1544    Addr# -> Int# -> Int# -> State# s -> State# s
1545    with has_side_effects = True
1546         can_fail         = True
1547
1548 primop  WriteOffAddrOp_Int32 "writeInt32OffAddr#" GenPrimOp
1549    Addr# -> Int# -> INT32 -> State# s -> State# s
1550    with has_side_effects = True
1551         can_fail         = True
1552
1553 primop  WriteOffAddrOp_Int64 "writeInt64OffAddr#" GenPrimOp
1554    Addr# -> Int# -> INT64 -> State# s -> State# s
1555    with has_side_effects = True
1556         can_fail         = True
1557
1558 primop  WriteOffAddrOp_Word8 "writeWord8OffAddr#" GenPrimOp
1559    Addr# -> Int# -> Word# -> State# s -> State# s
1560    with has_side_effects = True
1561         can_fail         = True
1562
1563 primop  WriteOffAddrOp_Word16 "writeWord16OffAddr#" GenPrimOp
1564    Addr# -> Int# -> Word# -> State# s -> State# s
1565    with has_side_effects = True
1566         can_fail         = True
1567
1568 primop  WriteOffAddrOp_Word32 "writeWord32OffAddr#" GenPrimOp
1569    Addr# -> Int# -> WORD32 -> State# s -> State# s
1570    with has_side_effects = True
1571         can_fail         = True
1572
1573 primop  WriteOffAddrOp_Word64 "writeWord64OffAddr#" GenPrimOp
1574    Addr# -> Int# -> WORD64 -> State# s -> State# s
1575    with has_side_effects = True
1576         can_fail         = True
1577
1578 ------------------------------------------------------------------------
1579 section "Mutable variables"
1580         {Operations on MutVar\#s.}
1581 ------------------------------------------------------------------------
1582
1583 primtype MutVar# s a
1584         {A {\tt MutVar\#} behaves like a single-element mutable array.}
1585
1586 primop  NewMutVarOp "newMutVar#" GenPrimOp
1587    a -> State# s -> (# State# s, MutVar# s a #)
1588    {Create {\tt MutVar\#} with specified initial value in specified state thread.}
1589    with
1590    out_of_line = True
1591    has_side_effects = True
1592
1593 primop  ReadMutVarOp "readMutVar#" GenPrimOp
1594    MutVar# s a -> State# s -> (# State# s, a #)
1595    {Read contents of {\tt MutVar\#}. Result is not yet evaluated.}
1596    with
1597    has_side_effects = True
1598    can_fail         = True
1599
1600 primop  WriteMutVarOp "writeMutVar#"  GenPrimOp
1601    MutVar# s a -> a -> State# s -> State# s
1602    {Write contents of {\tt MutVar\#}.}
1603    with
1604    has_side_effects = True
1605    code_size = { primOpCodeSizeForeignCall } -- for the write barrier
1606    can_fail         = True
1607
1608 primop  SameMutVarOp "sameMutVar#" GenPrimOp
1609    MutVar# s a -> MutVar# s a -> Int#
1610
1611 -- not really the right type, but we don't know about pairs here.  The
1612 -- correct type is
1613 --
1614 --   MutVar# s a -> (a -> (a,b)) -> State# s -> (# State# s, b #)
1615 --
1616 primop  AtomicModifyMutVarOp "atomicModifyMutVar#" GenPrimOp
1617    MutVar# s a -> (a -> b) -> State# s -> (# State# s, c #)
1618    with
1619    out_of_line = True
1620    has_side_effects = True
1621    can_fail         = True
1622
1623 primop  CasMutVarOp "casMutVar#" GenPrimOp
1624   MutVar# s a -> a -> a -> State# s -> (# State# s, Int#, a #)
1625    with
1626    out_of_line = True
1627    has_side_effects = True
1628
1629 ------------------------------------------------------------------------
1630 section "Exceptions"
1631 ------------------------------------------------------------------------
1632
1633 primop  CatchOp "catch#" GenPrimOp
1634           (State# RealWorld -> (# State# RealWorld, a #) )
1635        -> (b -> State# RealWorld -> (# State# RealWorld, a #) )
1636        -> State# RealWorld
1637        -> (# State# RealWorld, a #)
1638    with
1639         -- Catch is actually strict in its first argument
1640         -- but we don't want to tell the strictness
1641         -- analyser about that, so that exceptions stay inside it.
1642    strictness  = { \ _arity -> mkClosedStrictSig [apply1Dmd,apply2Dmd,topDmd] topRes }
1643    out_of_line = True
1644    has_side_effects = True
1645
1646 primop  RaiseOp "raise#" GenPrimOp
1647    a -> b
1648    with
1649    strictness  = { \ _arity -> mkClosedStrictSig [topDmd] botRes }
1650       -- NB: result is bottom
1651    out_of_line = True
1652
1653 -- raiseIO# needs to be a primop, because exceptions in the IO monad
1654 -- must be *precise* - we don't want the strictness analyser turning
1655 -- one kind of bottom into another, as it is allowed to do in pure code.
1656 --
1657 -- But we *do* want to know that it returns bottom after
1658 -- being applied to two arguments, so that this function is strict in y
1659 --     f x y | x>0       = raiseIO blah
1660 --           | y>0       = return 1
1661 --           | otherwise = return 2
1662
1663 primop  RaiseIOOp "raiseIO#" GenPrimOp
1664    a -> State# RealWorld -> (# State# RealWorld, b #)
1665    with
1666    strictness  = { \ _arity -> mkClosedStrictSig [topDmd, topDmd] botRes }
1667    out_of_line = True
1668    has_side_effects = True
1669
1670 primop  MaskAsyncExceptionsOp "maskAsyncExceptions#" GenPrimOp
1671         (State# RealWorld -> (# State# RealWorld, a #))
1672      -> (State# RealWorld -> (# State# RealWorld, a #))
1673    with
1674    strictness  = { \ _arity -> mkClosedStrictSig [apply1Dmd,topDmd] topRes }
1675    out_of_line = True
1676    has_side_effects = True
1677
1678 primop  MaskUninterruptibleOp "maskUninterruptible#" GenPrimOp
1679         (State# RealWorld -> (# State# RealWorld, a #))
1680      -> (State# RealWorld -> (# State# RealWorld, a #))
1681    with
1682    strictness  = { \ _arity -> mkClosedStrictSig [apply1Dmd,topDmd] topRes }
1683    out_of_line = True
1684    has_side_effects = True
1685
1686 primop  UnmaskAsyncExceptionsOp "unmaskAsyncExceptions#" GenPrimOp
1687         (State# RealWorld -> (# State# RealWorld, a #))
1688      -> (State# RealWorld -> (# State# RealWorld, a #))
1689    with
1690    strictness  = { \ _arity -> mkClosedStrictSig [apply1Dmd,topDmd] topRes }
1691    out_of_line = True
1692    has_side_effects = True
1693
1694 primop  MaskStatus "getMaskingState#" GenPrimOp
1695         State# RealWorld -> (# State# RealWorld, Int# #)
1696    with
1697    out_of_line = True
1698    has_side_effects = True
1699
1700 ------------------------------------------------------------------------
1701 section "STM-accessible Mutable Variables"
1702 ------------------------------------------------------------------------
1703
1704 primtype TVar# s a
1705
1706 primop  AtomicallyOp "atomically#" GenPrimOp
1707       (State# RealWorld -> (# State# RealWorld, a #) )
1708    -> State# RealWorld -> (# State# RealWorld, a #)
1709    with
1710    strictness  = { \ _arity -> mkClosedStrictSig [apply1Dmd,topDmd] topRes }
1711    out_of_line = True
1712    has_side_effects = True
1713
1714 -- NB: retry#'s strictness information specifies it to return bottom.
1715 -- This lets the compiler perform some extra simplifications, since retry#
1716 -- will technically never return.
1717 --
1718 -- This allows the simplifier to replace things like:
1719 --   case retry# s1
1720 --     (# s2, a #) -> e
1721 -- with:
1722 --   retry# s1
1723 -- where 'e' would be unreachable anyway.  See Trac #8091.
1724 primop  RetryOp "retry#" GenPrimOp
1725    State# RealWorld -> (# State# RealWorld, a #)
1726    with
1727    strictness  = { \ _arity -> mkClosedStrictSig [topDmd] botRes }
1728    out_of_line = True
1729    has_side_effects = True
1730
1731 primop  CatchRetryOp "catchRetry#" GenPrimOp
1732       (State# RealWorld -> (# State# RealWorld, a #) )
1733    -> (State# RealWorld -> (# State# RealWorld, a #) )
1734    -> (State# RealWorld -> (# State# RealWorld, a #) )
1735    with
1736    strictness  = { \ _arity -> mkClosedStrictSig [apply1Dmd,apply1Dmd,topDmd] topRes }
1737    out_of_line = True
1738    has_side_effects = True
1739
1740 primop  CatchSTMOp "catchSTM#" GenPrimOp
1741       (State# RealWorld -> (# State# RealWorld, a #) )
1742    -> (b -> State# RealWorld -> (# State# RealWorld, a #) )
1743    -> (State# RealWorld -> (# State# RealWorld, a #) )
1744    with
1745    strictness  = { \ _arity -> mkClosedStrictSig [apply1Dmd,apply2Dmd,topDmd] topRes }
1746    out_of_line = True
1747    has_side_effects = True
1748
1749 primop  Check "check#" GenPrimOp
1750       (State# RealWorld -> (# State# RealWorld, a #) )
1751    -> (State# RealWorld -> (# State# RealWorld, () #) )
1752    with
1753    out_of_line = True
1754    has_side_effects = True
1755
1756 primop  NewTVarOp "newTVar#" GenPrimOp
1757        a
1758     -> State# s -> (# State# s, TVar# s a #)
1759    {Create a new {\tt TVar\#} holding a specified initial value.}
1760    with
1761    out_of_line  = True
1762    has_side_effects = True
1763
1764 primop  ReadTVarOp "readTVar#" GenPrimOp
1765        TVar# s a
1766     -> State# s -> (# State# s, a #)
1767    {Read contents of {\tt TVar\#}.  Result is not yet evaluated.}
1768    with
1769    out_of_line  = True
1770    has_side_effects = True
1771
1772 primop ReadTVarIOOp "readTVarIO#" GenPrimOp
1773        TVar# s a
1774     -> State# s -> (# State# s, a #)
1775    {Read contents of {\tt TVar\#} outside an STM transaction}
1776    with
1777    out_of_line  = True
1778    has_side_effects = True
1779
1780 primop  WriteTVarOp "writeTVar#" GenPrimOp
1781        TVar# s a
1782     -> a
1783     -> State# s -> State# s
1784    {Write contents of {\tt TVar\#}.}
1785    with
1786    out_of_line      = True
1787    has_side_effects = True
1788
1789 primop  SameTVarOp "sameTVar#" GenPrimOp
1790    TVar# s a -> TVar# s a -> Int#
1791
1792
1793 ------------------------------------------------------------------------
1794 section "Synchronized Mutable Variables"
1795         {Operations on {\tt MVar\#}s. }
1796 ------------------------------------------------------------------------
1797
1798 primtype MVar# s a
1799         { A shared mutable variable ({\it not} the same as a {\tt MutVar\#}!).
1800         (Note: in a non-concurrent implementation, {\tt (MVar\# a)} can be
1801         represented by {\tt (MutVar\# (Maybe a))}.) }
1802
1803 primop  NewMVarOp "newMVar#"  GenPrimOp
1804    State# s -> (# State# s, MVar# s a #)
1805    {Create new {\tt MVar\#}; initially empty.}
1806    with
1807    out_of_line = True
1808    has_side_effects = True
1809
1810 primop  TakeMVarOp "takeMVar#" GenPrimOp
1811    MVar# s a -> State# s -> (# State# s, a #)
1812    {If {\tt MVar\#} is empty, block until it becomes full.
1813    Then remove and return its contents, and set it empty.}
1814    with
1815    out_of_line      = True
1816    has_side_effects = True
1817
1818 primop  TryTakeMVarOp "tryTakeMVar#" GenPrimOp
1819    MVar# s a -> State# s -> (# State# s, Int#, a #)
1820    {If {\tt MVar\#} is empty, immediately return with integer 0 and value undefined.
1821    Otherwise, return with integer 1 and contents of {\tt MVar\#}, and set {\tt MVar\#} empty.}
1822    with
1823    out_of_line      = True
1824    has_side_effects = True
1825
1826 primop  PutMVarOp "putMVar#" GenPrimOp
1827    MVar# s a -> a -> State# s -> State# s
1828    {If {\tt MVar\#} is full, block until it becomes empty.
1829    Then store value arg as its new contents.}
1830    with
1831    out_of_line      = True
1832    has_side_effects = True
1833
1834 primop  TryPutMVarOp "tryPutMVar#" GenPrimOp
1835    MVar# s a -> a -> State# s -> (# State# s, Int# #)
1836    {If {\tt MVar\#} is full, immediately return with integer 0.
1837     Otherwise, store value arg as {\tt MVar\#}'s new contents, and return with integer 1.}
1838    with
1839    out_of_line      = True
1840    has_side_effects = True
1841
1842 primop  ReadMVarOp "readMVar#" GenPrimOp
1843    MVar# s a -> State# s -> (# State# s, a #)
1844    {If {\tt MVar\#} is empty, block until it becomes full.
1845    Then read its contents without modifying the MVar, without possibility
1846    of intervention from other threads.}
1847    with
1848    out_of_line      = True
1849    has_side_effects = True
1850
1851 primop  TryReadMVarOp "tryReadMVar#" GenPrimOp
1852    MVar# s a -> State# s -> (# State# s, Int#, a #)
1853    {If {\tt MVar\#} is empty, immediately return with integer 0 and value undefined.
1854    Otherwise, return with integer 1 and contents of {\tt MVar\#}.}
1855    with
1856    out_of_line      = True
1857    has_side_effects = True
1858
1859 primop  SameMVarOp "sameMVar#" GenPrimOp
1860    MVar# s a -> MVar# s a -> Int#
1861
1862 primop  IsEmptyMVarOp "isEmptyMVar#" GenPrimOp
1863    MVar# s a -> State# s -> (# State# s, Int# #)
1864    {Return 1 if {\tt MVar\#} is empty; 0 otherwise.}
1865    with
1866    out_of_line = True
1867    has_side_effects = True
1868
1869 ------------------------------------------------------------------------
1870 section "Delay/wait operations"
1871 ------------------------------------------------------------------------
1872
1873 primop  DelayOp "delay#" GenPrimOp
1874    Int# -> State# s -> State# s
1875    {Sleep specified number of microseconds.}
1876    with
1877    has_side_effects = True
1878    out_of_line      = True
1879
1880 primop  WaitReadOp "waitRead#" GenPrimOp
1881    Int# -> State# s -> State# s
1882    {Block until input is available on specified file descriptor.}
1883    with
1884    has_side_effects = True
1885    out_of_line      = True
1886
1887 primop  WaitWriteOp "waitWrite#" GenPrimOp
1888    Int# -> State# s -> State# s
1889    {Block until output is possible on specified file descriptor.}
1890    with
1891    has_side_effects = True
1892    out_of_line      = True
1893
1894 #ifdef mingw32_TARGET_OS
1895 primop  AsyncReadOp "asyncRead#" GenPrimOp
1896    Int# -> Int# -> Int# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
1897    {Asynchronously read bytes from specified file descriptor.}
1898    with
1899    has_side_effects = True
1900    out_of_line      = True
1901
1902 primop  AsyncWriteOp "asyncWrite#" GenPrimOp
1903    Int# -> Int# -> Int# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
1904    {Asynchronously write bytes from specified file descriptor.}
1905    with
1906    has_side_effects = True
1907    out_of_line      = True
1908
1909 primop  AsyncDoProcOp "asyncDoProc#" GenPrimOp
1910    Addr# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
1911    {Asynchronously perform procedure (first arg), passing it 2nd arg.}
1912    with
1913    has_side_effects = True
1914    out_of_line      = True
1915
1916 #endif
1917
1918 ------------------------------------------------------------------------
1919 section "Concurrency primitives"
1920 ------------------------------------------------------------------------
1921
1922 primtype State# s
1923         { {\tt State\#} is the primitive, unlifted type of states.  It has
1924         one type parameter, thus {\tt State\# RealWorld}, or {\tt State\# s},
1925         where s is a type variable. The only purpose of the type parameter
1926         is to keep different state threads separate.  It is represented by
1927         nothing at all. }
1928
1929 primtype RealWorld
1930         { {\tt RealWorld} is deeply magical.  It is {\it primitive}, but it is not
1931         {\it unlifted} (hence {\tt ptrArg}).  We never manipulate values of type
1932         {\tt RealWorld}; it's only used in the type system, to parameterise {\tt State\#}. }
1933
1934 primtype ThreadId#
1935         {(In a non-concurrent implementation, this can be a singleton
1936         type, whose (unique) value is returned by {\tt myThreadId\#}.  The
1937         other operations can be omitted.)}
1938
1939 primop  ForkOp "fork#" GenPrimOp
1940    a -> State# RealWorld -> (# State# RealWorld, ThreadId# #)
1941    with
1942    has_side_effects = True
1943    out_of_line      = True
1944
1945 primop  ForkOnOp "forkOn#" GenPrimOp
1946    Int# -> a -> State# RealWorld -> (# State# RealWorld, ThreadId# #)
1947    with
1948    has_side_effects = True
1949    out_of_line      = True
1950
1951 primop  KillThreadOp "killThread#"  GenPrimOp
1952    ThreadId# -> a -> State# RealWorld -> State# RealWorld
1953    with
1954    has_side_effects = True
1955    out_of_line      = True
1956
1957 primop  YieldOp "yield#" GenPrimOp
1958    State# RealWorld -> State# RealWorld
1959    with
1960    has_side_effects = True
1961    out_of_line      = True
1962
1963 primop  MyThreadIdOp "myThreadId#" GenPrimOp
1964    State# RealWorld -> (# State# RealWorld, ThreadId# #)
1965    with
1966    out_of_line = True
1967    has_side_effects = True
1968
1969 primop LabelThreadOp "labelThread#" GenPrimOp
1970    ThreadId# -> Addr# -> State# RealWorld -> State# RealWorld
1971    with
1972    has_side_effects = True
1973    out_of_line      = True
1974
1975 primop  IsCurrentThreadBoundOp "isCurrentThreadBound#" GenPrimOp
1976    State# RealWorld -> (# State# RealWorld, Int# #)
1977    with
1978    out_of_line = True
1979    has_side_effects = True
1980
1981 primop  NoDuplicateOp "noDuplicate#" GenPrimOp
1982    State# RealWorld -> State# RealWorld
1983    with
1984    out_of_line = True
1985    has_side_effects = True
1986
1987 primop  ThreadStatusOp "threadStatus#" GenPrimOp
1988    ThreadId# -> State# RealWorld -> (# State# RealWorld, Int#, Int#, Int# #)
1989    with
1990    out_of_line = True
1991    has_side_effects = True
1992
1993 ------------------------------------------------------------------------
1994 section "Weak pointers"
1995 ------------------------------------------------------------------------
1996
1997 primtype Weak# b
1998
1999 -- note that tyvar "o" denotes openAlphaTyVar
2000
2001 primop  MkWeakOp "mkWeak#" GenPrimOp
2002    o -> b -> c -> State# RealWorld -> (# State# RealWorld, Weak# b #)
2003    with
2004    has_side_effects = True
2005    out_of_line      = True
2006
2007 primop  MkWeakNoFinalizerOp "mkWeakNoFinalizer#" GenPrimOp
2008    o -> b -> State# RealWorld -> (# State# RealWorld, Weak# b #)
2009    with
2010    has_side_effects = True
2011    out_of_line      = True
2012
2013 primop  AddCFinalizerToWeakOp "addCFinalizerToWeak#" GenPrimOp
2014    Addr# -> Addr# -> Int# -> Addr# -> Weak# b
2015           -> State# RealWorld -> (# State# RealWorld, Int# #)
2016    { {\tt addCFinalizerToWeak# fptr ptr flag eptr w} attaches a C
2017      function pointer {\tt fptr} to a weak pointer {\tt w} as a finalizer. If
2018      {\tt flag} is zero, {\tt fptr} will be called with one argument,
2019      {\tt ptr}. Otherwise, it will be called with two arguments,
2020      {\tt eptr} and {\tt ptr}. {\tt addCFinalizerToWeak#} returns
2021      1 on success, or 0 if {\tt w} is already dead. }
2022    with
2023    has_side_effects = True
2024    out_of_line      = True
2025
2026 primop  DeRefWeakOp "deRefWeak#" GenPrimOp
2027    Weak# a -> State# RealWorld -> (# State# RealWorld, Int#, a #)
2028    with
2029    has_side_effects = True
2030    out_of_line      = True
2031
2032 primop  FinalizeWeakOp "finalizeWeak#" GenPrimOp
2033    Weak# a -> State# RealWorld -> (# State# RealWorld, Int#,
2034               (State# RealWorld -> (# State# RealWorld, () #)) #)
2035    with
2036    has_side_effects = True
2037    out_of_line      = True
2038
2039 primop TouchOp "touch#" GenPrimOp
2040    o -> State# RealWorld -> State# RealWorld
2041    with
2042    code_size = { 0 }
2043    has_side_effects = True
2044
2045 ------------------------------------------------------------------------
2046 section "Stable pointers and names"
2047 ------------------------------------------------------------------------
2048
2049 primtype StablePtr# a
2050
2051 primtype StableName# a
2052
2053 primop  MakeStablePtrOp "makeStablePtr#" GenPrimOp
2054    a -> State# RealWorld -> (# State# RealWorld, StablePtr# a #)
2055    with
2056    has_side_effects = True
2057    out_of_line      = True
2058
2059 primop  DeRefStablePtrOp "deRefStablePtr#" GenPrimOp
2060    StablePtr# a -> State# RealWorld -> (# State# RealWorld, a #)
2061    with
2062    has_side_effects = True
2063    out_of_line      = True
2064
2065 primop  EqStablePtrOp "eqStablePtr#" GenPrimOp
2066    StablePtr# a -> StablePtr# a -> Int#
2067    with
2068    has_side_effects = True
2069
2070 primop  MakeStableNameOp "makeStableName#" GenPrimOp
2071    a -> State# RealWorld -> (# State# RealWorld, StableName# a #)
2072    with
2073    has_side_effects = True
2074    out_of_line      = True
2075
2076 primop  EqStableNameOp "eqStableName#" GenPrimOp
2077    StableName# a -> StableName# b -> Int#
2078
2079 primop  StableNameToIntOp "stableNameToInt#" GenPrimOp
2080    StableName# a -> Int#
2081
2082 ------------------------------------------------------------------------
2083 section "Unsafe pointer equality"
2084 --  (#1 Bad Guy: Alistair Reid :)
2085 ------------------------------------------------------------------------
2086
2087 primop  ReallyUnsafePtrEqualityOp "reallyUnsafePtrEquality#" GenPrimOp
2088    a -> a -> Int#
2089
2090 ------------------------------------------------------------------------
2091 section "Parallelism"
2092 ------------------------------------------------------------------------
2093
2094 primop  ParOp "par#" GenPrimOp
2095    a -> Int#
2096    with
2097       -- Note that Par is lazy to avoid that the sparked thing
2098       -- gets evaluted strictly, which it should *not* be
2099    has_side_effects = True
2100    code_size = { primOpCodeSizeForeignCall }
2101
2102 primop SparkOp "spark#" GenPrimOp
2103    a -> State# s -> (# State# s, a #)
2104    with has_side_effects = True
2105    code_size = { primOpCodeSizeForeignCall }
2106
2107 primop SeqOp "seq#" GenPrimOp
2108    a -> State# s -> (# State# s, a #)
2109
2110    -- why return the value?  So that we can control sharing of seq'd
2111    -- values: in
2112    --    let x = e in x `seq` ... x ...
2113    -- we don't want to inline x, so better to represent it as
2114    --    let x = e in case seq# x RW of (# _, x' #) -> ... x' ...
2115    -- also it matches the type of rseq in the Eval monad.
2116
2117 primop GetSparkOp "getSpark#" GenPrimOp
2118    State# s -> (# State# s, Int#, a #)
2119    with
2120    has_side_effects = True
2121    out_of_line = True
2122
2123 primop NumSparks "numSparks#" GenPrimOp
2124    State# s -> (# State# s, Int# #)
2125    { Returns the number of sparks in the local spark pool. }
2126    with
2127    has_side_effects = True
2128    out_of_line = True
2129
2130 -- HWL: The first 4 Int# in all par... annotations denote:
2131 --   name, granularity info, size of result, degree of parallelism
2132 --      Same  structure as _seq_ i.e. returns Int#
2133 -- KSW: v, the second arg in parAt# and parAtForNow#, is used only to determine
2134 --   `the processor containing the expression v'; it is not evaluated
2135
2136 primop  ParGlobalOp  "parGlobal#"  GenPrimOp
2137    a -> Int# -> Int# -> Int# -> Int# -> b -> Int#
2138    with
2139    has_side_effects = True
2140
2141 primop  ParLocalOp  "parLocal#"  GenPrimOp
2142    a -> Int# -> Int# -> Int# -> Int# -> b -> Int#
2143    with
2144    has_side_effects = True
2145
2146 primop  ParAtOp  "parAt#"  GenPrimOp
2147    b -> a -> Int# -> Int# -> Int# -> Int# -> c -> Int#
2148    with
2149    has_side_effects = True
2150
2151 primop  ParAtAbsOp  "parAtAbs#"  GenPrimOp
2152    a -> Int# -> Int# -> Int# -> Int# -> Int# -> b -> Int#
2153    with
2154    has_side_effects = True
2155
2156 primop  ParAtRelOp  "parAtRel#" GenPrimOp
2157    a -> Int# -> Int# -> Int# -> Int# -> Int# -> b -> Int#
2158    with
2159    has_side_effects = True
2160
2161 primop  ParAtForNowOp  "parAtForNow#" GenPrimOp
2162    b -> a -> Int# -> Int# -> Int# -> Int# -> c -> Int#
2163    with
2164    has_side_effects = True
2165
2166 -- copyable# and noFollow# are yet to be implemented (for GpH)
2167 --
2168 --primop  CopyableOp  "copyable#" GenPrimOp
2169 --   a -> Int#
2170 --   with
2171 --   has_side_effects = True
2172 --
2173 --primop  NoFollowOp "noFollow#" GenPrimOp
2174 --   a -> Int#
2175 --   with
2176 --   has_side_effects = True
2177
2178
2179 ------------------------------------------------------------------------
2180 section "Tag to enum stuff"
2181         {Convert back and forth between values of enumerated types
2182         and small integers.}
2183 ------------------------------------------------------------------------
2184
2185 primop  DataToTagOp "dataToTag#" GenPrimOp
2186    a -> Int#
2187    with
2188    strictness  = { \ _arity -> mkClosedStrictSig [evalDmd] topRes }
2189
2190         -- dataToTag# must have an evaluated argument
2191
2192 primop  TagToEnumOp "tagToEnum#" GenPrimOp
2193    Int# -> a
2194
2195 ------------------------------------------------------------------------
2196 section "Bytecode operations"
2197         {Support for the bytecode interpreter and linker.}
2198 ------------------------------------------------------------------------
2199
2200 primtype BCO#
2201    {Primitive bytecode type.}
2202
2203 primop   AddrToAnyOp "addrToAny#" GenPrimOp
2204    Addr# -> (# a #)
2205    {Convert an {\tt Addr\#} to a followable Any type.}
2206    with
2207    code_size = 0
2208
2209 primop   MkApUpd0_Op "mkApUpd0#" GenPrimOp
2210    BCO# -> (# a #)
2211    with
2212    out_of_line = True
2213
2214 primop  NewBCOOp "newBCO#" GenPrimOp
2215    ByteArray# -> ByteArray# -> Array# a -> Int# -> ByteArray# -> State# s -> (# State# s, BCO# #)
2216    with
2217    has_side_effects = True
2218    out_of_line      = True
2219
2220 primop  UnpackClosureOp "unpackClosure#" GenPrimOp
2221    a -> (# Addr#, Array# b, ByteArray# #)
2222    with
2223    out_of_line = True
2224
2225 primop  GetApStackValOp "getApStackVal#" GenPrimOp
2226    a -> Int# -> (# Int#, b #)
2227    with
2228    out_of_line = True
2229
2230 ------------------------------------------------------------------------
2231 section "Misc"
2232         {These aren't nearly as wired in as Etc...}
2233 ------------------------------------------------------------------------
2234
2235 primop  GetCCSOfOp "getCCSOf#" GenPrimOp
2236    a -> State# s -> (# State# s, Addr# #)
2237
2238 primop  GetCurrentCCSOp "getCurrentCCS#" GenPrimOp
2239    a -> State# s -> (# State# s, Addr# #)
2240    { Returns the current {\tt CostCentreStack} (value is {\tt NULL} if
2241      not profiling).  Takes a dummy argument which can be used to
2242      avoid the call to {\tt getCCCS\#} being floated out by the
2243      simplifier, which would result in an uninformative stack
2244      ("CAF"). }
2245
2246 ------------------------------------------------------------------------
2247 section "Etc"
2248         {Miscellaneous built-ins}
2249 ------------------------------------------------------------------------
2250
2251 primtype Proxy# a
2252    { The type constructor {\tt Proxy#} is used to bear witness to some
2253    type variable. It's used when you want to pass around proxy values
2254    for doing things like modelling type applications. A {\tt Proxy#}
2255    is not only unboxed, it also has a polymorphic kind, and has no
2256    runtime representation, being totally free. }
2257
2258 pseudoop "proxy#"
2259    Proxy# a
2260    { Witness for an unboxed {\tt Proxy#} value, which has no runtime
2261    representation. }
2262
2263 pseudoop   "seq"
2264    a -> b -> b
2265    { Evaluates its first argument to head normal form, and then returns its second
2266         argument as the result. }
2267
2268 primtype Any k
2269         { The type constructor {\tt Any} is type to which you can unsafely coerce any
2270         lifted type, and back.
2271
2272           * It is lifted, and hence represented by a pointer
2273
2274           * It does not claim to be a {\it data} type, and that's important for
2275             the code generator, because the code gen may {\it enter} a data value
2276             but never enters a function value.
2277
2278         It's also used to instantiate un-constrained type variables after type
2279         checking.  For example, {\tt length} has type
2280
2281         {\tt length :: forall a. [a] -> Int}
2282
2283         and the list datacon for the empty list has type
2284
2285         {\tt [] :: forall a. [a]}
2286
2287         In order to compose these two terms as {\tt length []} a type
2288         application is required, but there is no constraint on the
2289         choice.  In this situation GHC uses {\tt Any}:
2290
2291         {\tt length (Any *) ([] (Any *))}
2292
2293         Note that {\tt Any} is kind polymorphic, and takes a kind {\tt k} as its
2294         first argument. The kind of {\tt Any} is thus {\tt forall k. k -> k}.}
2295
2296 primtype AnyK
2297         { The kind {\tt AnyK} is the kind level counterpart to {\tt Any}. In a
2298         kind polymorphic setting, a similar example to the length of the empty
2299         list can be given at the type level:
2300
2301         {\tt type family Length (l :: [k]) :: Nat}
2302         {\tt type instance Length [] = Zero}
2303
2304         When {\tt Length} is applied to the empty (promoted) list it will have
2305         the kind {\tt Length AnyK []}.
2306
2307         {\tt AnyK} is currently not exported and cannot be used directly, but
2308         you might see it in debug output from the compiler.
2309         }
2310
2311 pseudoop   "unsafeCoerce#"
2312    a -> b
2313    { The function {\tt unsafeCoerce\#} allows you to side-step the typechecker entirely. That
2314         is, it allows you to coerce any type into any other type. If you use this function,
2315         you had better get it right, otherwise segmentation faults await. It is generally
2316         used when you want to write a program that you know is well-typed, but where Haskell's
2317         type system is not expressive enough to prove that it is well typed.
2318
2319         The following uses of {\tt unsafeCoerce\#} are supposed to work (i.e. not lead to
2320         spurious compile-time or run-time crashes):
2321
2322          * Casting any lifted type to {\tt Any}
2323
2324          * Casting {\tt Any} back to the real type
2325
2326          * Casting an unboxed type to another unboxed type of the same size
2327            (but not coercions between floating-point and integral types)
2328
2329          * Casting between two types that have the same runtime representation.  One case is when
2330            the two types differ only in "phantom" type parameters, for example
2331            {\tt Ptr Int} to {\tt Ptr Float}, or {\tt [Int]} to {\tt [Float]} when the list is
2332            known to be empty.  Also, a {\tt newtype} of a type {\tt T} has the same representation
2333            at runtime as {\tt T}.
2334
2335         Other uses of {\tt unsafeCoerce\#} are undefined.  In particular, you should not use
2336         {\tt unsafeCoerce\#} to cast a T to an algebraic data type D, unless T is also
2337         an algebraic data type.  For example, do not cast {\tt Int->Int} to {\tt Bool}, even if
2338         you later cast that {\tt Bool} back to {\tt Int->Int} before applying it.  The reasons
2339         have to do with GHC's internal representation details (for the congnoscenti, data values
2340         can be entered but function closures cannot).  If you want a safe type to cast things
2341         to, use {\tt Any}, which is not an algebraic data type.
2342
2343         }
2344
2345 -- NB. It is tempting to think that casting a value to a type that it doesn't have is safe
2346 -- as long as you don't "do anything" with the value in its cast form, such as seq on it.  This
2347 -- isn't the case: the compiler can insert seqs itself, and if these happen at the wrong type,
2348 -- Bad Things Might Happen.  See bug #1616: in this case we cast a function of type (a,b) -> (a,b)
2349 -- to () -> () and back again.  The strictness analyser saw that the function was strict, but
2350 -- the wrapper had type () -> (), and hence the wrapper de-constructed the (), the worker re-constructed
2351 -- a new (), with the result that the code ended up with "case () of (a,b) -> ...".
2352
2353 primop  TraceEventOp "traceEvent#" GenPrimOp
2354    Addr# -> State# s -> State# s
2355    { Emits an event via the RTS tracing framework.  The contents
2356      of the event is the zero-terminated byte string passed as the first
2357      argument.  The event will be emitted either to the .eventlog file,
2358      or to stderr, depending on the runtime RTS flags. }
2359    with
2360    has_side_effects = True
2361    out_of_line      = True
2362
2363 primop  TraceMarkerOp "traceMarker#" GenPrimOp
2364    Addr# -> State# s -> State# s
2365    { Emits a marker event via the RTS tracing framework.  The contents
2366      of the event is the zero-terminated byte string passed as the first
2367      argument.  The event will be emitted either to the .eventlog file,
2368      or to stderr, depending on the runtime RTS flags. }
2369    with
2370    has_side_effects = True
2371    out_of_line      = True
2372
2373 ------------------------------------------------------------------------
2374 section "Safe coercions"
2375 ------------------------------------------------------------------------
2376
2377 pseudoop   "coerce"
2378    Coercible a b => a -> b
2379    { The function {\tt coerce} allows you to safely convert between values of
2380      types that have the same representation with no run-time overhead. In the
2381      simplest case you can use it instead of a newtype constructor, to go from
2382      the newtype's concrete type to the abstract type. But it also works in
2383      more complicated settings, e.g. converting a list of newtypes to a list of
2384      concrete types.
2385    }
2386
2387 ------------------------------------------------------------------------
2388 section "SIMD Vectors"
2389         {Operations on SIMD vectors.}
2390 ------------------------------------------------------------------------
2391
2392 #define ALL_VECTOR_TYPES \
2393   [<Int8,Int#,16>,<Int16,Int#,8>,<Int32,INT32,4>,<Int64,INT64,2> \
2394   ,<Int8,Int#,32>,<Int16,Int#,16>,<Int32,INT32,8>,<Int64,INT64,4> \
2395   ,<Int8,Int#,64>,<Int16,Int#,32>,<Int32,INT32,16>,<Int64,INT64,8> \
2396   ,<Word8,Word#,16>,<Word16,Word#,8>,<Word32,WORD32,4>,<Word64,WORD64,2> \
2397   ,<Word8,Word#,32>,<Word16,Word#,16>,<Word32,WORD32,8>,<Word64,WORD64,4> \
2398   ,<Word8,Word#,64>,<Word16,Word#,32>,<Word32,WORD32,16>,<Word64,WORD64,8> \
2399   ,<Float,Float#,4>,<Double,Double#,2> \
2400   ,<Float,Float#,8>,<Double,Double#,4> \
2401   ,<Float,Float#,16>,<Double,Double#,8>]
2402
2403 #define SIGNED_VECTOR_TYPES \
2404   [<Int8,Int#,16>,<Int16,Int#,8>,<Int32,INT32,4>,<Int64,INT64,2> \
2405   ,<Int8,Int#,32>,<Int16,Int#,16>,<Int32,INT32,8>,<Int64,INT64,4> \
2406   ,<Int8,Int#,64>,<Int16,Int#,32>,<Int32,INT32,16>,<Int64,INT64,8> \
2407   ,<Float,Float#,4>,<Double,Double#,2> \
2408   ,<Float,Float#,8>,<Double,Double#,4> \
2409   ,<Float,Float#,16>,<Double,Double#,8>]
2410
2411 #define FLOAT_VECTOR_TYPES \
2412   [<Float,Float#,4>,<Double,Double#,2> \
2413   ,<Float,Float#,8>,<Double,Double#,4> \
2414   ,<Float,Float#,16>,<Double,Double#,8>]
2415
2416 #define INT_VECTOR_TYPES \
2417   [<Int8,Int#,16>,<Int16,Int#,8>,<Int32,INT32,4>,<Int64,INT64,2> \
2418   ,<Int8,Int#,32>,<Int16,Int#,16>,<Int32,INT32,8>,<Int64,INT64,4> \
2419   ,<Int8,Int#,64>,<Int16,Int#,32>,<Int32,INT32,16>,<Int64,INT64,8> \
2420   ,<Word8,Word#,16>,<Word16,Word#,8>,<Word32,WORD32,4>,<Word64,WORD64,2> \
2421   ,<Word8,Word#,32>,<Word16,Word#,16>,<Word32,WORD32,8>,<Word64,WORD64,4> \
2422   ,<Word8,Word#,64>,<Word16,Word#,32>,<Word32,WORD32,16>,<Word64,WORD64,8>]
2423
2424 primtype VECTOR
2425    with llvm_only = True
2426         vector = ALL_VECTOR_TYPES
2427
2428 primop VecBroadcastOp "broadcast#" GenPrimOp
2429    SCALAR -> VECTOR
2430    { Broadcast a scalar to all elements of a vector. }
2431    with llvm_only = True
2432         vector = ALL_VECTOR_TYPES
2433
2434 primop VecPackOp "pack#" GenPrimOp
2435    VECTUPLE -> VECTOR
2436    { Pack the elements of an unboxed tuple into a vector. }
2437    with llvm_only = True
2438         vector = ALL_VECTOR_TYPES
2439
2440 primop VecUnpackOp "unpack#" GenPrimOp
2441    VECTOR -> VECTUPLE
2442    { Unpack the elements of a vector into an unboxed tuple. #}
2443    with llvm_only = True
2444         vector = ALL_VECTOR_TYPES
2445
2446 primop VecInsertOp "insert#" GenPrimOp
2447    VECTOR -> SCALAR -> Int# -> VECTOR
2448    { Insert a scalar at the given position in a vector. }
2449    with can_fail = True
2450         llvm_only = True
2451         vector = ALL_VECTOR_TYPES
2452
2453 primop VecAddOp "plus#" Dyadic
2454    VECTOR -> VECTOR -> VECTOR
2455    { Add two vectors element-wise. }
2456    with commutable = True
2457         llvm_only = True
2458         vector = ALL_VECTOR_TYPES
2459
2460 primop VecSubOp "minus#" Dyadic
2461    VECTOR -> VECTOR -> VECTOR
2462    { Subtract two vectors element-wise. }
2463    with llvm_only = True
2464         vector = ALL_VECTOR_TYPES
2465
2466 primop VecMulOp "times#" Dyadic
2467    VECTOR -> VECTOR -> VECTOR
2468    { Multiply two vectors element-wise. }
2469    with commutable = True
2470         llvm_only = True
2471         vector = ALL_VECTOR_TYPES
2472
2473 primop VecDivOp "divide#" Dyadic
2474    VECTOR -> VECTOR -> VECTOR
2475    { Divide two vectors element-wise. }
2476    with can_fail = True
2477         llvm_only = True
2478         vector = FLOAT_VECTOR_TYPES
2479
2480 primop VecQuotOp "quot#" Dyadic
2481    VECTOR -> VECTOR -> VECTOR
2482    { Rounds towards zero element-wise. }
2483    with can_fail = True
2484         llvm_only = True
2485         vector = INT_VECTOR_TYPES
2486
2487 primop VecRemOp "rem#" Dyadic
2488    VECTOR -> VECTOR -> VECTOR
2489    { Satisfies \texttt{(quot\# x y) times\# y plus\# (rem\# x y) == x}. }
2490    with can_fail = True
2491         llvm_only = True
2492         vector = INT_VECTOR_TYPES
2493
2494 primop VecNegOp "negate#" Monadic
2495    VECTOR -> VECTOR
2496    { Negate element-wise. }
2497    with llvm_only = True
2498         vector = SIGNED_VECTOR_TYPES
2499
2500 primop VecIndexByteArrayOp "indexArray#" GenPrimOp
2501    ByteArray# -> Int# -> VECTOR
2502    { Read a vector from specified index of immutable array. }
2503    with can_fail = True
2504         llvm_only = True
2505         vector = ALL_VECTOR_TYPES
2506
2507 primop VecReadByteArrayOp "readArray#" GenPrimOp
2508    MutableByteArray# s -> Int# -> State# s -> (# State# s, VECTOR #)
2509    { Read a vector from specified index of mutable array. }
2510    with has_side_effects = True
2511         can_fail = True
2512         llvm_only = True
2513         vector = ALL_VECTOR_TYPES
2514
2515 primop VecWriteByteArrayOp "writeArray#" GenPrimOp
2516    MutableByteArray# s -> Int# -> VECTOR -> State# s -> State# s
2517    { Write a vector to specified index of mutable array. }
2518    with has_side_effects = True
2519         can_fail = True
2520         llvm_only = True
2521         vector = ALL_VECTOR_TYPES
2522
2523 primop VecIndexOffAddrOp "indexOffAddr#" GenPrimOp
2524    Addr# -> Int# -> VECTOR
2525    { Reads vector; offset in bytes. }
2526    with can_fail = True
2527         llvm_only = True
2528         vector = ALL_VECTOR_TYPES
2529
2530 primop VecReadOffAddrOp "readOffAddr#" GenPrimOp
2531    Addr# -> Int# -> State# s -> (# State# s, VECTOR #)
2532    { Reads vector; offset in bytes. }
2533    with has_side_effects = True
2534         can_fail = True
2535         llvm_only = True
2536         vector = ALL_VECTOR_TYPES
2537
2538 primop VecWriteOffAddrOp "writeOffAddr#" GenPrimOp
2539    Addr# -> Int# -> VECTOR -> State# s -> State# s
2540    { Write vector; offset in bytes. }
2541    with has_side_effects = True
2542         can_fail = True
2543         llvm_only = True
2544         vector = ALL_VECTOR_TYPES
2545
2546
2547 primop VecIndexScalarByteArrayOp "indexArrayAs#" GenPrimOp
2548    ByteArray# -> Int# -> VECTOR
2549    { Read a vector from specified index of immutable array of scalars; offset is in scalar elements. }
2550    with can_fail = True
2551         llvm_only = True
2552         vector = ALL_VECTOR_TYPES
2553
2554 primop VecReadScalarByteArrayOp "readArrayAs#" GenPrimOp
2555    MutableByteArray# s -> Int# -> State# s -> (# State# s, VECTOR #)
2556    { Read a vector from specified index of mutable array of scalars; offset is in scalar elements. }
2557    with has_side_effects = True
2558         can_fail = True
2559         llvm_only = True
2560         vector = ALL_VECTOR_TYPES
2561
2562 primop VecWriteScalarByteArrayOp "writeArrayAs#" GenPrimOp
2563    MutableByteArray# s -> Int# -> VECTOR -> State# s -> State# s
2564    { Write a vector to specified index of mutable array of scalars; offset is in scalar elements. }
2565    with has_side_effects = True
2566         can_fail = True
2567         llvm_only = True
2568         vector = ALL_VECTOR_TYPES
2569
2570 primop VecIndexScalarOffAddrOp "indexOffAddrAs#" GenPrimOp
2571    Addr# -> Int# -> VECTOR
2572    { Reads vector; offset in scalar elements. }
2573    with can_fail = True
2574         llvm_only = True
2575         vector = ALL_VECTOR_TYPES
2576
2577 primop VecReadScalarOffAddrOp "readOffAddrAs#" GenPrimOp
2578    Addr# -> Int# -> State# s -> (# State# s, VECTOR #)
2579    { Reads vector; offset in scalar elements. }
2580    with has_side_effects = True
2581         can_fail = True
2582         llvm_only = True
2583         vector = ALL_VECTOR_TYPES
2584
2585 primop VecWriteScalarOffAddrOp "writeOffAddrAs#" GenPrimOp
2586    Addr# -> Int# -> VECTOR -> State# s -> State# s
2587    { Write vector; offset in scalar elements. }
2588    with has_side_effects = True
2589         can_fail = True
2590         llvm_only = True
2591         vector = ALL_VECTOR_TYPES
2592
2593 ------------------------------------------------------------------------
2594
2595 section "Prefetch"
2596         {Prefetch operations: Note how every prefetch operation has a name
2597   with the pattern prefetch*N#, where N is either 0,1,2, or 3.
2598
2599   This suffix number, N, is the "locality level" of the prefetch, following the
2600   convention in GCC and other compilers.
2601   Higher locality numbers correspond to the memory being loaded in more
2602   levels of the cpu cache, and being retained after initial use. The naming
2603   convention follows the naming convention of the prefetch intrinsic found
2604   in the GCC and Clang C compilers.
2605
2606   On the LLVM backend, prefetch*N# uses the LLVM prefetch intrinsic
2607   with locality level N. The code generated by LLVM is target architecture
2608   dependent, but should agree with the GHC NCG on x86 systems.
2609
2610   On the Sparc and PPC native backends, prefetch*N is a No-Op.
2611
2612   On the x86 NCG, N=0 will generate prefetchNTA,
2613   N=1 generates prefetcht2, N=2 generates prefetcht1, and
2614   N=3 generates prefetcht0.
2615
2616   For streaming workloads, the prefetch*0 operations are recommended.
2617   For workloads which do many reads or writes to a memory location in a short period of time,
2618   prefetch*3 operations are recommended.
2619
2620   For further reading about prefetch and associated systems performance optimization,
2621   the instruction set and optimization manuals by Intel and other CPU vendors are
2622   excellent starting place.
2623
2624
2625   The "Intel 64 and IA-32 Architectures Optimization Reference Manual" is
2626   especially a helpful read, even if your software is meant for other CPU
2627   architectures or vendor hardware. The manual can be found at
2628   http://www.intel.com/content/www/us/en/architecture-and-technology/64-ia-32-architectures-optimization-manual.html .
2629
2630   The {\tt prefetchMutableByteArray} family of operations has the order of operations
2631   determined by passing around the {\tt State#} token.
2632
2633   For the {\tt prefetchByteArray}
2634   and {\tt prefetchAddr} families of operations, consider the following example:
2635
2636   {\tt let a1 = prefetchByteArray2# a n in ...a1... }
2637
2638   In the above fragement, {\tt a} is the input variable for the prefetch
2639   and {\tt a1 == a} will be true. To ensure that the prefetch is not treated as deadcode,
2640   the body of the let should only use {\tt a1} and NOT {\tt a}. The same principle
2641   applies for uses of prefetch in a loop.
2642
2643   }
2644
2645
2646 ------------------------------------------------------------------------
2647
2648
2649 --- the Int# argument for prefetch is the byte offset on the byteArray or  Addr#
2650
2651 ---
2652 primop PrefetchByteArrayOp3 "prefetchByteArray3#" GenPrimOp
2653    ByteArray# -> Int# -> ByteArray#
2654
2655 primop PrefetchMutableByteArrayOp3 "prefetchMutableByteArray3#" GenPrimOp
2656    MutableByteArray# s -> Int# -> State# s -> State# s
2657
2658 primop PrefetchAddrOp3 "prefetchAddr3#" GenPrimOp
2659     Addr# -> Int# -> Addr#
2660
2661 ----
2662
2663 primop PrefetchByteArrayOp2 "prefetchByteArray2#" GenPrimOp
2664    ByteArray# -> Int# -> ByteArray#
2665
2666 primop PrefetchMutableByteArrayOp2 "prefetchMutableByteArray2#" GenPrimOp
2667    MutableByteArray# s -> Int# -> State# s -> State# s
2668
2669 primop PrefetchAddrOp2 "prefetchAddr2#" GenPrimOp
2670    Addr# -> Int# -> Addr#
2671
2672 ----
2673
2674 primop PrefetchByteArrayOp1 "prefetchByteArray1#" GenPrimOp
2675    ByteArray# -> Int# -> ByteArray#
2676
2677 primop PrefetchMutableByteArrayOp1 "prefetchMutableByteArray1#" GenPrimOp
2678    MutableByteArray# s -> Int# -> State# s -> State# s
2679
2680 primop PrefetchAddrOp1 "prefetchAddr1#" GenPrimOp
2681    Addr# -> Int# -> Addr#
2682
2683 ----
2684
2685 primop PrefetchByteArrayOp0 "prefetchByteArray0#" GenPrimOp
2686    ByteArray# -> Int# -> ByteArray#
2687
2688 primop PrefetchMutableByteArrayOp0 "prefetchMutableByteArray0#" GenPrimOp
2689    MutableByteArray# s -> Int# -> State# s -> State# s
2690
2691 primop PrefetchAddrOp0 "prefetchAddr0#" GenPrimOp
2692    Addr# -> Int# -> Addr#
2693
2694
2695
2696 ------------------------------------------------------------------------
2697 ---                                                                  ---
2698 ------------------------------------------------------------------------
2699
2700 thats_all_folks