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