primops: Generate ByteArray# index/read/write primops

Previously these were mostly undocumented and was ripe for potential
inconsistencies.

2 files changed, 359 insertions, 113 deletions

diff --git a/compiler/GHC/Builtin/bytearray-ops.txt.pp b/compiler/GHC/Builtin/bytearray-ops.txt.pp
index 0e91a7a9d9..75f420479f 100644
--- a/compiler/GHC/Builtin/bytearray-ops.txt.pp
+++ b/compiler/GHC/Builtin/bytearray-ops.txt.pp
@@ -1,449 +1,551 @@
+
+------------------------------------
+-- ByteArray# operations
+------------------------------------
+
+
+-- Do not edit. This file is generated by utils/genprimopcode/gen_bytearray_ops.py.
+-- To regenerate run,
+--
+--      python3 utils/genprimops/gen_bytearray_ops.py > compiler/GHC/Builtin/bytearray-ops.txt.pp
+
+
+------------------------------------
+-- aligned index operations
+------------------------------------
+
 primop IndexByteArrayOp_Char "indexCharArray#" GenPrimOp
    ByteArray# -> Int# -> Char#
-   {Read 8-bit character; offset in bytes.}
+   {Read a 8-bit character; offset in bytes.}
    with can_fail = True
 
 primop IndexByteArrayOp_WideChar "indexWideCharArray#" GenPrimOp
    ByteArray# -> Int# -> Char#
-   {Read 31-bit character; offset in 4-byte words.}
+   {Read a 32-bit character; offset in 4-byte words.}
    with can_fail = True
 
 primop IndexByteArrayOp_Int "indexIntArray#" GenPrimOp
    ByteArray# -> Int# -> Int#
+   {Read a word-sized integer; offset in machine words.}
    with can_fail = True
 
 primop IndexByteArrayOp_Word "indexWordArray#" GenPrimOp
    ByteArray# -> Int# -> Word#
+   {Read a word-sized unsigned integer; offset in machine words.}
    with can_fail = True
 
 primop IndexByteArrayOp_Addr "indexAddrArray#" GenPrimOp
    ByteArray# -> Int# -> Addr#
+   {Read a machine address; offset in machine words.}
    with can_fail = True
 
 primop IndexByteArrayOp_Float "indexFloatArray#" GenPrimOp
    ByteArray# -> Int# -> Float#
+   {Read a single-precision floating-point value; offset in 4-byte words.}
    with can_fail = True
 
 primop IndexByteArrayOp_Double "indexDoubleArray#" GenPrimOp
    ByteArray# -> Int# -> Double#
+   {Read a double-precision floating-point value; offset in 8-byte words.}
    with can_fail = True
 
 primop IndexByteArrayOp_StablePtr "indexStablePtrArray#" GenPrimOp
    ByteArray# -> Int# -> StablePtr# a
+   {Read a {\tt StablePtr#} value; offset in machine words.}
    with can_fail = True
 
 primop IndexByteArrayOp_Int8 "indexInt8Array#" GenPrimOp
    ByteArray# -> Int# -> Int#
-   {Read 8-bit integer; offset in bytes.}
+   {Read a 8-bit signed integer; offset in bytes.}
    with can_fail = True
 
 primop IndexByteArrayOp_Int16 "indexInt16Array#" GenPrimOp
    ByteArray# -> Int# -> Int#
-   {Read 16-bit integer; offset in 16-bit words.}
+   {Read a 16-bit signed integer; offset in 2-byte words.}
    with can_fail = True
 
 primop IndexByteArrayOp_Int32 "indexInt32Array#" GenPrimOp
    ByteArray# -> Int# -> INT32
-   {Read 32-bit integer; offset in 32-bit words.}
+   {Read a 32-bit signed integer; offset in 4-byte words.}
    with can_fail = True
 
 primop IndexByteArrayOp_Int64 "indexInt64Array#" GenPrimOp
    ByteArray# -> Int# -> INT64
-   {Read 64-bit integer; offset in 64-bit words.}
+   {Read a 64-bit signed integer; offset in 8-byte words.}
    with can_fail = True
 
 primop IndexByteArrayOp_Word8 "indexWord8Array#" GenPrimOp
    ByteArray# -> Int# -> Word#
-   {Read 8-bit word; offset in bytes.}
+   {Read a 8-bit unsigned integer; offset in bytes.}
    with can_fail = True
 
 primop IndexByteArrayOp_Word16 "indexWord16Array#" GenPrimOp
    ByteArray# -> Int# -> Word#
-   {Read 16-bit word; offset in 16-bit words.}
+   {Read a 16-bit unsigned integer; offset in 2-byte words.}
    with can_fail = True
 
 primop IndexByteArrayOp_Word32 "indexWord32Array#" GenPrimOp
    ByteArray# -> Int# -> WORD32
-   {Read 32-bit word; offset in 32-bit words.}
+   {Read a 32-bit unsigned integer; offset in 4-byte words.}
    with can_fail = True
 
 primop IndexByteArrayOp_Word64 "indexWord64Array#" GenPrimOp
    ByteArray# -> Int# -> WORD64
-   {Read 64-bit word; offset in 64-bit words.}
+   {Read a 64-bit unsigned integer; offset in 8-byte words.}
    with can_fail = True
 
+
+------------------------------------
+-- unaligned index operations
+------------------------------------
+
 primop IndexByteArrayOp_Word8AsChar "indexWord8ArrayAsChar#" GenPrimOp
    ByteArray# -> Int# -> Char#
-   {Read 8-bit character; offset in bytes.}
+   {Read a 8-bit character; offset in bytes.}
    with can_fail = True
 
 primop IndexByteArrayOp_Word8AsWideChar "indexWord8ArrayAsWideChar#" GenPrimOp
    ByteArray# -> Int# -> Char#
-   {Read 31-bit character; offset in bytes.}
+   {Read a 32-bit character; offset in bytes.}
+   with can_fail = True
+
+primop IndexByteArrayOp_Word8AsInt "indexWord8ArrayAsInt#" GenPrimOp
+   ByteArray# -> Int# -> Int#
+   {Read a word-sized integer; offset in bytes.}
+   with can_fail = True
+
+primop IndexByteArrayOp_Word8AsWord "indexWord8ArrayAsWord#" GenPrimOp
+   ByteArray# -> Int# -> Word#
+   {Read a word-sized unsigned integer; offset in bytes.}
    with can_fail = True
 
 primop IndexByteArrayOp_Word8AsAddr "indexWord8ArrayAsAddr#" GenPrimOp
    ByteArray# -> Int# -> Addr#
-   {Read address; offset in bytes.}
+   {Read a machine address; offset in bytes.}
    with can_fail = True
 
 primop IndexByteArrayOp_Word8AsFloat "indexWord8ArrayAsFloat#" GenPrimOp
    ByteArray# -> Int# -> Float#
-   {Read float; offset in bytes.}
+   {Read a single-precision floating-point value; offset in bytes.}
    with can_fail = True
 
 primop IndexByteArrayOp_Word8AsDouble "indexWord8ArrayAsDouble#" GenPrimOp
    ByteArray# -> Int# -> Double#
-   {Read double; offset in bytes.}
+   {Read a double-precision floating-point value; offset in bytes.}
    with can_fail = True
 
 primop IndexByteArrayOp_Word8AsStablePtr "indexWord8ArrayAsStablePtr#" GenPrimOp
    ByteArray# -> Int# -> StablePtr# a
-   {Read stable pointer; offset in bytes.}
+   {Read a {\tt StablePtr#} value; offset in bytes.}
    with can_fail = True
 
 primop IndexByteArrayOp_Word8AsInt16 "indexWord8ArrayAsInt16#" GenPrimOp
    ByteArray# -> Int# -> Int#
-   {Read 16-bit int; offset in bytes.}
+   {Read a 16-bit signed integer; offset in bytes.}
    with can_fail = True
 
 primop IndexByteArrayOp_Word8AsInt32 "indexWord8ArrayAsInt32#" GenPrimOp
    ByteArray# -> Int# -> INT32
-   {Read 32-bit int; offset in bytes.}
+   {Read a 32-bit signed integer; offset in bytes.}
    with can_fail = True
 
 primop IndexByteArrayOp_Word8AsInt64 "indexWord8ArrayAsInt64#" GenPrimOp
    ByteArray# -> Int# -> INT64
-   {Read 64-bit int; offset in bytes.}
-   with can_fail = True
-
-primop IndexByteArrayOp_Word8AsInt "indexWord8ArrayAsInt#" GenPrimOp
-   ByteArray# -> Int# -> Int#
-   {Read int; offset in bytes.}
+   {Read a 64-bit signed integer; offset in bytes.}
    with can_fail = True
 
 primop IndexByteArrayOp_Word8AsWord16 "indexWord8ArrayAsWord16#" GenPrimOp
    ByteArray# -> Int# -> Word#
-   {Read 16-bit word; offset in bytes.}
+   {Read a 16-bit unsigned integer; offset in bytes.}
    with can_fail = True
 
 primop IndexByteArrayOp_Word8AsWord32 "indexWord8ArrayAsWord32#" GenPrimOp
    ByteArray# -> Int# -> WORD32
-   {Read 32-bit word; offset in bytes.}
+   {Read a 32-bit unsigned integer; offset in bytes.}
    with can_fail = True
 
 primop IndexByteArrayOp_Word8AsWord64 "indexWord8ArrayAsWord64#" GenPrimOp
    ByteArray# -> Int# -> WORD64
-   {Read 64-bit word; offset in bytes.}
+   {Read a 64-bit unsigned integer; offset in bytes.}
    with can_fail = True
 
-primop IndexByteArrayOp_Word8AsWord "indexWord8ArrayAsWord#" GenPrimOp
-   ByteArray# -> Int# -> Word#
-   {Read word; offset in bytes.}
-   with can_fail = True
 
-primop  ReadByteArrayOp_Char "readCharArray#" GenPrimOp
+------------------------------------
+-- aligned read operations
+------------------------------------
+
+primop ReadByteArrayOp_Char "readCharArray#" GenPrimOp
    MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
-   {Read 8-bit character; offset in bytes.}
+   {Read a 8-bit character; offset in bytes.}
    with has_side_effects = True
         can_fail = True
 
-primop  ReadByteArrayOp_WideChar "readWideCharArray#" GenPrimOp
+primop ReadByteArrayOp_WideChar "readWideCharArray#" GenPrimOp
    MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
-   {Read 31-bit character; offset in 4-byte words.}
+   {Read a 32-bit character; offset in 4-byte words.}
    with has_side_effects = True
         can_fail = True
 
-primop  ReadByteArrayOp_Int "readIntArray#" GenPrimOp
+primop ReadByteArrayOp_Int "readIntArray#" GenPrimOp
    MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
-   {Read integer; offset in machine words.}
+   {Read a word-sized integer; offset in machine words.}
    with has_side_effects = True
         can_fail = True
 
-primop  ReadByteArrayOp_Word "readWordArray#" GenPrimOp
+primop ReadByteArrayOp_Word "readWordArray#" GenPrimOp
    MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
-   {Read word; offset in machine words.}
+   {Read a word-sized unsigned integer; offset in machine words.}
    with has_side_effects = True
         can_fail = True
 
-primop  ReadByteArrayOp_Addr "readAddrArray#" GenPrimOp
+primop ReadByteArrayOp_Addr "readAddrArray#" GenPrimOp
    MutableByteArray# s -> Int# -> State# s -> (# State# s, Addr# #)
+   {Read a machine address; offset in machine words.}
    with has_side_effects = True
         can_fail = True
 
-primop  ReadByteArrayOp_Float "readFloatArray#" GenPrimOp
+primop ReadByteArrayOp_Float "readFloatArray#" GenPrimOp
    MutableByteArray# s -> Int# -> State# s -> (# State# s, Float# #)
+   {Read a single-precision floating-point value; offset in 4-byte words.}
    with has_side_effects = True
         can_fail = True
 
-primop  ReadByteArrayOp_Double "readDoubleArray#" GenPrimOp
+primop ReadByteArrayOp_Double "readDoubleArray#" GenPrimOp
    MutableByteArray# s -> Int# -> State# s -> (# State# s, Double# #)
+   {Read a double-precision floating-point value; offset in 8-byte words.}
    with has_side_effects = True
         can_fail = True
 
-primop  ReadByteArrayOp_StablePtr "readStablePtrArray#" GenPrimOp
+primop ReadByteArrayOp_StablePtr "readStablePtrArray#" GenPrimOp
    MutableByteArray# s -> Int# -> State# s -> (# State# s, StablePtr# a #)
+   {Read a {\tt StablePtr#} value; offset in machine words.}
    with has_side_effects = True
         can_fail = True
 
-primop  ReadByteArrayOp_Int8 "readInt8Array#" GenPrimOp
+primop ReadByteArrayOp_Int8 "readInt8Array#" GenPrimOp
    MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
+   {Read a 8-bit signed integer; offset in bytes.}
    with has_side_effects = True
         can_fail = True
 
-primop  ReadByteArrayOp_Int16 "readInt16Array#" GenPrimOp
+primop ReadByteArrayOp_Int16 "readInt16Array#" GenPrimOp
    MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
+   {Read a 16-bit signed integer; offset in 2-byte words.}
    with has_side_effects = True
         can_fail = True
 
-primop  ReadByteArrayOp_Int32 "readInt32Array#" GenPrimOp
+primop ReadByteArrayOp_Int32 "readInt32Array#" GenPrimOp
    MutableByteArray# s -> Int# -> State# s -> (# State# s, INT32 #)
+   {Read a 32-bit signed integer; offset in 4-byte words.}
    with has_side_effects = True
         can_fail = True
 
-primop  ReadByteArrayOp_Int64 "readInt64Array#" GenPrimOp
+primop ReadByteArrayOp_Int64 "readInt64Array#" GenPrimOp
    MutableByteArray# s -> Int# -> State# s -> (# State# s, INT64 #)
+   {Read a 64-bit signed integer; offset in 8-byte words.}
    with has_side_effects = True
         can_fail = True
 
-primop  ReadByteArrayOp_Word8 "readWord8Array#" GenPrimOp
+primop ReadByteArrayOp_Word8 "readWord8Array#" GenPrimOp
    MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
+   {Read a 8-bit unsigned integer; offset in bytes.}
    with has_side_effects = True
         can_fail = True
 
-primop  ReadByteArrayOp_Word16 "readWord16Array#" GenPrimOp
+primop ReadByteArrayOp_Word16 "readWord16Array#" GenPrimOp
    MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
+   {Read a 16-bit unsigned integer; offset in 2-byte words.}
    with has_side_effects = True
         can_fail = True
 
-primop  ReadByteArrayOp_Word32 "readWord32Array#" GenPrimOp
+primop ReadByteArrayOp_Word32 "readWord32Array#" GenPrimOp
    MutableByteArray# s -> Int# -> State# s -> (# State# s, WORD32 #)
+   {Read a 32-bit unsigned integer; offset in 4-byte words.}
    with has_side_effects = True
         can_fail = True
 
-primop  ReadByteArrayOp_Word64 "readWord64Array#" GenPrimOp
+primop ReadByteArrayOp_Word64 "readWord64Array#" GenPrimOp
    MutableByteArray# s -> Int# -> State# s -> (# State# s, WORD64 #)
+   {Read a 64-bit unsigned integer; offset in 8-byte words.}
    with has_side_effects = True
         can_fail = True
 
-primop  ReadByteArrayOp_Word8AsChar "readWord8ArrayAsChar#" GenPrimOp
+
+------------------------------------
+-- unaligned read operations
+------------------------------------
+
+primop ReadByteArrayOp_Word8AsChar "readWord8ArrayAsChar#" GenPrimOp
    MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
+   {Read a 8-bit character; offset in bytes.}
    with has_side_effects = True
         can_fail = True
 
-primop  ReadByteArrayOp_Word8AsWideChar "readWord8ArrayAsWideChar#" GenPrimOp
+primop ReadByteArrayOp_Word8AsWideChar "readWord8ArrayAsWideChar#" GenPrimOp
    MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
+   {Read a 32-bit character; offset in bytes.}
+   with has_side_effects = True
+        can_fail = True
+
+primop ReadByteArrayOp_Word8AsInt "readWord8ArrayAsInt#" GenPrimOp
+   MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
+   {Read a word-sized integer; offset in bytes.}
+   with has_side_effects = True
+        can_fail = True
+
+primop ReadByteArrayOp_Word8AsWord "readWord8ArrayAsWord#" GenPrimOp
+   MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
+   {Read a word-sized unsigned integer; offset in bytes.}
    with has_side_effects = True
         can_fail = True
 
-primop  ReadByteArrayOp_Word8AsAddr "readWord8ArrayAsAddr#" GenPrimOp
+primop ReadByteArrayOp_Word8AsAddr "readWord8ArrayAsAddr#" GenPrimOp
    MutableByteArray# s -> Int# -> State# s -> (# State# s, Addr# #)
+   {Read a machine address; offset in bytes.}
    with has_side_effects = True
         can_fail = True
 
-primop  ReadByteArrayOp_Word8AsFloat "readWord8ArrayAsFloat#" GenPrimOp
+primop ReadByteArrayOp_Word8AsFloat "readWord8ArrayAsFloat#" GenPrimOp
    MutableByteArray# s -> Int# -> State# s -> (# State# s, Float# #)
+   {Read a single-precision floating-point value; offset in bytes.}
    with has_side_effects = True
         can_fail = True
 
-primop  ReadByteArrayOp_Word8AsDouble "readWord8ArrayAsDouble#" GenPrimOp
+primop ReadByteArrayOp_Word8AsDouble "readWord8ArrayAsDouble#" GenPrimOp
    MutableByteArray# s -> Int# -> State# s -> (# State# s, Double# #)
+   {Read a double-precision floating-point value; offset in bytes.}
    with has_side_effects = True
         can_fail = True
 
-primop  ReadByteArrayOp_Word8AsStablePtr "readWord8ArrayAsStablePtr#" GenPrimOp
+primop ReadByteArrayOp_Word8AsStablePtr "readWord8ArrayAsStablePtr#" GenPrimOp
    MutableByteArray# s -> Int# -> State# s -> (# State# s, StablePtr# a #)
+   {Read a {\tt StablePtr#} value; offset in bytes.}
    with has_side_effects = True
         can_fail = True
 
-primop  ReadByteArrayOp_Word8AsInt16 "readWord8ArrayAsInt16#" GenPrimOp
+primop ReadByteArrayOp_Word8AsInt16 "readWord8ArrayAsInt16#" GenPrimOp
    MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
+   {Read a 16-bit signed integer; offset in bytes.}
    with has_side_effects = True
         can_fail = True
 
-primop  ReadByteArrayOp_Word8AsInt32 "readWord8ArrayAsInt32#" GenPrimOp
+primop ReadByteArrayOp_Word8AsInt32 "readWord8ArrayAsInt32#" GenPrimOp
    MutableByteArray# s -> Int# -> State# s -> (# State# s, INT32 #)
+   {Read a 32-bit signed integer; offset in bytes.}
    with has_side_effects = True
         can_fail = True
 
-primop  ReadByteArrayOp_Word8AsInt64 "readWord8ArrayAsInt64#" GenPrimOp
+primop ReadByteArrayOp_Word8AsInt64 "readWord8ArrayAsInt64#" GenPrimOp
    MutableByteArray# s -> Int# -> State# s -> (# State# s, INT64 #)
+   {Read a 64-bit signed integer; offset in bytes.}
    with has_side_effects = True
         can_fail = True
 
-primop  ReadByteArrayOp_Word8AsInt "readWord8ArrayAsInt#" GenPrimOp
-   MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
-   with has_side_effects = True
-        can_fail = True
-
-primop  ReadByteArrayOp_Word8AsWord16 "readWord8ArrayAsWord16#" GenPrimOp
+primop ReadByteArrayOp_Word8AsWord16 "readWord8ArrayAsWord16#" GenPrimOp
    MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
+   {Read a 16-bit unsigned integer; offset in bytes.}
    with has_side_effects = True
         can_fail = True
 
-primop  ReadByteArrayOp_Word8AsWord32 "readWord8ArrayAsWord32#" GenPrimOp
+primop ReadByteArrayOp_Word8AsWord32 "readWord8ArrayAsWord32#" GenPrimOp
    MutableByteArray# s -> Int# -> State# s -> (# State# s, WORD32 #)
+   {Read a 32-bit unsigned integer; offset in bytes.}
    with has_side_effects = True
         can_fail = True
 
-primop  ReadByteArrayOp_Word8AsWord64 "readWord8ArrayAsWord64#" GenPrimOp
+primop ReadByteArrayOp_Word8AsWord64 "readWord8ArrayAsWord64#" GenPrimOp
    MutableByteArray# s -> Int# -> State# s -> (# State# s, WORD64 #)
+   {Read a 64-bit unsigned integer; offset in bytes.}
    with has_side_effects = True
         can_fail = True
 
-primop  ReadByteArrayOp_Word8AsWord "readWord8ArrayAsWord#" GenPrimOp
-   MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
-   with has_side_effects = True
-        can_fail = True
 
-primop  WriteByteArrayOp_Char "writeCharArray#" GenPrimOp
+------------------------------------
+-- aligned write operations
+------------------------------------
+
+primop WriteByteArrayOp_Char "writeCharArray#" GenPrimOp
    MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
-   {Write 8-bit character; offset in bytes.}
+   {Write a 8-bit character; offset in bytes.}
    with has_side_effects = True
         can_fail = True
 
-primop  WriteByteArrayOp_WideChar "writeWideCharArray#" GenPrimOp
+primop WriteByteArrayOp_WideChar "writeWideCharArray#" GenPrimOp
    MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
-   {Write 31-bit character; offset in 4-byte words.}
+   {Write a 32-bit character; offset in 4-byte words.}
    with has_side_effects = True
         can_fail = True
 
-primop  WriteByteArrayOp_Int "writeIntArray#" GenPrimOp
+primop WriteByteArrayOp_Int "writeIntArray#" GenPrimOp
    MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
+   {Write a word-sized integer; offset in machine words.}
    with has_side_effects = True
         can_fail = True
 
-primop  WriteByteArrayOp_Word "writeWordArray#" GenPrimOp
+primop WriteByteArrayOp_Word "writeWordArray#" GenPrimOp
    MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
+   {Write a word-sized unsigned integer; offset in machine words.}
    with has_side_effects = True
         can_fail = True
 
-primop  WriteByteArrayOp_Addr "writeAddrArray#" GenPrimOp
+primop WriteByteArrayOp_Addr "writeAddrArray#" GenPrimOp
    MutableByteArray# s -> Int# -> Addr# -> State# s -> State# s
+   {Write a machine address; offset in machine words.}
    with has_side_effects = True
         can_fail = True
 
-primop  WriteByteArrayOp_Float "writeFloatArray#" GenPrimOp
+primop WriteByteArrayOp_Float "writeFloatArray#" GenPrimOp
    MutableByteArray# s -> Int# -> Float# -> State# s -> State# s
+   {Write a single-precision floating-point value; offset in 4-byte words.}
    with has_side_effects = True
         can_fail = True
 
-primop  WriteByteArrayOp_Double "writeDoubleArray#" GenPrimOp
+primop WriteByteArrayOp_Double "writeDoubleArray#" GenPrimOp
    MutableByteArray# s -> Int# -> Double# -> State# s -> State# s
+   {Write a double-precision floating-point value; offset in 8-byte words.}
    with has_side_effects = True
         can_fail = True
 
-primop  WriteByteArrayOp_StablePtr "writeStablePtrArray#" GenPrimOp
+primop WriteByteArrayOp_StablePtr "writeStablePtrArray#" GenPrimOp
    MutableByteArray# s -> Int# -> StablePtr# a -> State# s -> State# s
+   {Write a {\tt StablePtr#} value; offset in machine words.}
    with has_side_effects = True
         can_fail = True
 
-primop  WriteByteArrayOp_Int8 "writeInt8Array#" GenPrimOp
+primop WriteByteArrayOp_Int8 "writeInt8Array#" GenPrimOp
    MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
+   {Write a 8-bit signed integer; offset in bytes.}
    with has_side_effects = True
         can_fail = True
 
-primop  WriteByteArrayOp_Int16 "writeInt16Array#" GenPrimOp
+primop WriteByteArrayOp_Int16 "writeInt16Array#" GenPrimOp
    MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
+   {Write a 16-bit signed integer; offset in 2-byte words.}
    with has_side_effects = True
         can_fail = True
 
-primop  WriteByteArrayOp_Int32 "writeInt32Array#" GenPrimOp
+primop WriteByteArrayOp_Int32 "writeInt32Array#" GenPrimOp
    MutableByteArray# s -> Int# -> INT32 -> State# s -> State# s
+   {Write a 32-bit signed integer; offset in 4-byte words.}
    with has_side_effects = True
         can_fail = True
 
-primop  WriteByteArrayOp_Int64 "writeInt64Array#" GenPrimOp
+primop WriteByteArrayOp_Int64 "writeInt64Array#" GenPrimOp
    MutableByteArray# s -> Int# -> INT64 -> State# s -> State# s
-   with can_fail = True
-        has_side_effects = True
+   {Write a 64-bit signed integer; offset in 8-byte words.}
+   with has_side_effects = True
+        can_fail = True
 
-primop  WriteByteArrayOp_Word8 "writeWord8Array#" GenPrimOp
+primop WriteByteArrayOp_Word8 "writeWord8Array#" GenPrimOp
    MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
+   {Write a 8-bit unsigned integer; offset in bytes.}
    with has_side_effects = True
         can_fail = True
 
-primop  WriteByteArrayOp_Word16 "writeWord16Array#" GenPrimOp
+primop WriteByteArrayOp_Word16 "writeWord16Array#" GenPrimOp
    MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
+   {Write a 16-bit unsigned integer; offset in 2-byte words.}
    with has_side_effects = True
         can_fail = True
 
-primop  WriteByteArrayOp_Word32 "writeWord32Array#" GenPrimOp
+primop WriteByteArrayOp_Word32 "writeWord32Array#" GenPrimOp
    MutableByteArray# s -> Int# -> WORD32 -> State# s -> State# s
+   {Write a 32-bit unsigned integer; offset in 4-byte words.}
    with has_side_effects = True
         can_fail = True
 
-primop  WriteByteArrayOp_Word64 "writeWord64Array#" GenPrimOp
+primop WriteByteArrayOp_Word64 "writeWord64Array#" GenPrimOp
    MutableByteArray# s -> Int# -> WORD64 -> State# s -> State# s
+   {Write a 64-bit unsigned integer; offset in 8-byte words.}
    with has_side_effects = True
         can_fail = True
 
-primop  WriteByteArrayOp_Word8AsChar "writeWord8ArrayAsChar#" GenPrimOp
+
+------------------------------------
+-- unaligned write operations
+------------------------------------
+
+primop WriteByteArrayOp_Word8AsChar "writeWord8ArrayAsChar#" GenPrimOp
    MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
+   {Write a 8-bit character; offset in bytes.}
    with has_side_effects = True
         can_fail = True
 
-primop  WriteByteArrayOp_Word8AsWideChar "writeWord8ArrayAsWideChar#" GenPrimOp
+primop WriteByteArrayOp_Word8AsWideChar "writeWord8ArrayAsWideChar#" GenPrimOp
    MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
+   {Write a 32-bit character; offset in bytes.}
    with has_side_effects = True
         can_fail = True
 
-primop  WriteByteArrayOp_Word8AsAddr "writeWord8ArrayAsAddr#" GenPrimOp
+primop WriteByteArrayOp_Word8AsInt "writeWord8ArrayAsInt#" GenPrimOp
+   MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
+   {Write a word-sized integer; offset in bytes.}
+   with has_side_effects = True
+        can_fail = True
+
+primop WriteByteArrayOp_Word8AsWord "writeWord8ArrayAsWord#" GenPrimOp
+   MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
+   {Write a word-sized unsigned integer; offset in bytes.}
+   with has_side_effects = True
+        can_fail = True
+
+primop WriteByteArrayOp_Word8AsAddr "writeWord8ArrayAsAddr#" GenPrimOp
    MutableByteArray# s -> Int# -> Addr# -> State# s -> State# s
+   {Write a machine address; offset in bytes.}
    with has_side_effects = True
         can_fail = True
 
-primop  WriteByteArrayOp_Word8AsFloat "writeWord8ArrayAsFloat#" GenPrimOp
+primop WriteByteArrayOp_Word8AsFloat "writeWord8ArrayAsFloat#" GenPrimOp
    MutableByteArray# s -> Int# -> Float# -> State# s -> State# s
+   {Write a single-precision floating-point value; offset in bytes.}
    with has_side_effects = True
         can_fail = True
 
-primop  WriteByteArrayOp_Word8AsDouble "writeWord8ArrayAsDouble#" GenPrimOp
+primop WriteByteArrayOp_Word8AsDouble "writeWord8ArrayAsDouble#" GenPrimOp
    MutableByteArray# s -> Int# -> Double# -> State# s -> State# s
+   {Write a double-precision floating-point value; offset in bytes.}
    with has_side_effects = True
         can_fail = True
 
-primop  WriteByteArrayOp_Word8AsStablePtr "writeWord8ArrayAsStablePtr#" GenPrimOp
+primop WriteByteArrayOp_Word8AsStablePtr "writeWord8ArrayAsStablePtr#" GenPrimOp
    MutableByteArray# s -> Int# -> StablePtr# a -> State# s -> State# s
+   {Write a {\tt StablePtr#} value; offset in bytes.}
    with has_side_effects = True
         can_fail = True
 
-primop  WriteByteArrayOp_Word8AsInt16 "writeWord8ArrayAsInt16#" GenPrimOp
+primop WriteByteArrayOp_Word8AsInt16 "writeWord8ArrayAsInt16#" GenPrimOp
    MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
+   {Write a 16-bit signed integer; offset in bytes.}
    with has_side_effects = True
         can_fail = True
 
-primop  WriteByteArrayOp_Word8AsInt32 "writeWord8ArrayAsInt32#" GenPrimOp
+primop WriteByteArrayOp_Word8AsInt32 "writeWord8ArrayAsInt32#" GenPrimOp
    MutableByteArray# s -> Int# -> INT32 -> State# s -> State# s
+   {Write a 32-bit signed integer; offset in bytes.}
    with has_side_effects = True
         can_fail = True
 
-primop  WriteByteArrayOp_Word8AsInt64 "writeWord8ArrayAsInt64#" GenPrimOp
+primop WriteByteArrayOp_Word8AsInt64 "writeWord8ArrayAsInt64#" GenPrimOp
    MutableByteArray# s -> Int# -> INT64 -> State# s -> State# s
+   {Write a 64-bit signed integer; offset in bytes.}
    with has_side_effects = True
         can_fail = True
 
-primop  WriteByteArrayOp_Word8AsInt "writeWord8ArrayAsInt#" GenPrimOp
-   MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
-   with has_side_effects = True
-        can_fail = True
-
-primop  WriteByteArrayOp_Word8AsWord16 "writeWord8ArrayAsWord16#" GenPrimOp
+primop WriteByteArrayOp_Word8AsWord16 "writeWord8ArrayAsWord16#" GenPrimOp
    MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
+   {Write a 16-bit unsigned integer; offset in bytes.}
    with has_side_effects = True
         can_fail = True
 
-primop  WriteByteArrayOp_Word8AsWord32 "writeWord8ArrayAsWord32#" GenPrimOp
+primop WriteByteArrayOp_Word8AsWord32 "writeWord8ArrayAsWord32#" GenPrimOp
    MutableByteArray# s -> Int# -> WORD32 -> State# s -> State# s
+   {Write a 32-bit unsigned integer; offset in bytes.}
    with has_side_effects = True
         can_fail = True
 
-primop  WriteByteArrayOp_Word8AsWord64 "writeWord8ArrayAsWord64#" GenPrimOp
+primop WriteByteArrayOp_Word8AsWord64 "writeWord8ArrayAsWord64#" GenPrimOp
    MutableByteArray# s -> Int# -> WORD64 -> State# s -> State# s
+   {Write a 64-bit unsigned integer; offset in bytes.}
    with has_side_effects = True
         can_fail = True
 
-primop  WriteByteArrayOp_Word8AsWord "writeWord8ArrayAsWord#" GenPrimOp
-   MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
-   with has_side_effects = True
-        can_fail = True
diff --git a/utils/genprimopcode/gen_bytearray_ops.py b/utils/genprimopcode/gen_bytearray_ops.py
new file mode 100644
index 0000000000..760ad150c9
--- /dev/null
+++ b/utils/genprimopcode/gen_bytearray_ops.py
@@ -0,0 +1,144 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+from typing import Optional, NamedTuple
+import textwrap
+
+class ElementType(NamedTuple):
+    name: str
+    rep_ty: str
+    desc: str
+    width: Optional[int]
+
+MACH_WORD = None
+
+element_types = [
+    # (name, representation type, human description, width)
+    #
+    # width in bytes.
+    # width == None denotes machine word
+
+    ElementType("Char",      "Char#",        "8-bit character",                       1),
+    ElementType("WideChar",  "Char#",        "32-bit character",                      4),
+    ElementType("Int",       "Int#",         "word-sized integer",                    MACH_WORD),
+    ElementType("Word",      "Word#",        "word-sized unsigned integer",           MACH_WORD),
+    ElementType("Addr",      "Addr#",        "machine address",                       MACH_WORD),
+    ElementType("Float",     "Float#",       "single-precision floating-point value", 4),
+    ElementType("Double",    "Double#",      "double-precision floating-point value", 8),
+    ElementType("StablePtr", "StablePtr# a", "{\\tt StablePtr#} value",               MACH_WORD),
+]
+
+# TODO: Eventually when the sized integer primops use proper unboxed types we
+# should rather do:
+#
+#for n in [8,16,32,64]:
+#    element_types += [ ElementType(f"Int{n}",  f"Int{n}#",  f"{n}-bit signed integer",   n // 8) ]
+#
+#for n in [8,16,32,64]:
+#    element_types += [ ElementType(f"Word{n}", f"Word{n}#", f"{n}-bit unsigned integer", n // 8) ]
+
+element_types += [
+    ElementType("Int8",   "Int#",  "8-bit signed integer",  1),
+    ElementType("Int16",  "Int#",  "16-bit signed integer", 2),
+    ElementType("Int32",  "INT32", "32-bit signed integer", 4),
+    ElementType("Int64",  "INT64", "64-bit signed integer", 8),
+
+    ElementType("Word8",  "Word#",  "8-bit unsigned integer",  1),
+    ElementType("Word16", "Word#",  "16-bit unsigned integer", 2),
+    ElementType("Word32", "WORD32", "32-bit unsigned integer", 4),
+    ElementType("Word64", "WORD64", "64-bit unsigned integer", 8),
+]
+
+def pretty_offset(n: Optional[int]) -> str:
+    if n == MACH_WORD:
+        return 'machine words'
+    elif n == 1:
+        return 'bytes'
+    else:
+        return f'{n}-byte words'
+
+def print_block(template: str, **kwargs) -> None:
+    print(textwrap.dedent(template.format(**kwargs)).lstrip())
+
+def header(s: str):
+    print('')
+    print_block('''
+        ------------------------------------
+        -- {s}
+        ------------------------------------
+    ''', s=s)
+
+
+header("ByteArray# operations")
+
+print('''
+-- Do not edit. This file is generated by utils/genprimopcode/gen_bytearray_ops.py.
+-- To regenerate run,
+--
+--      python3 utils/genprimops/gen_bytearray_ops.py > compiler/GHC/Builtin/bytearray-ops.txt.pp
+''')
+
+header('aligned index operations')
+for t in element_types:
+    offset = pretty_offset(t.width)
+    print_block('''
+        primop IndexByteArrayOp_{name} "index{name}Array#" GenPrimOp
+           ByteArray# -> Int# -> {rep_ty}
+           {{Read a {desc}; offset in {offset}.}}
+           with can_fail = True
+    ''', offset = offset, **t._asdict())
+
+header('unaligned index operations')
+for t in element_types:
+    if t.name in ['Int8', 'Word8']: continue
+    print_block('''
+        primop IndexByteArrayOp_Word8As{name} "indexWord8ArrayAs{name}#" GenPrimOp
+           ByteArray# -> Int# -> {rep_ty}
+           {{Read a {desc}; offset in bytes.}}
+           with can_fail = True
+    ''', **t._asdict())
+
+header('aligned read operations')
+for t in element_types:
+    offset = pretty_offset(t.width)
+    print_block('''
+        primop ReadByteArrayOp_{name} "read{name}Array#" GenPrimOp
+           MutableByteArray# s -> Int# -> State# s -> (# State# s, {rep_ty} #)
+           {{Read a {desc}; offset in {offset}.}}
+           with has_side_effects = True
+                can_fail = True
+    ''', offset = offset, **t._asdict())
+
+header('unaligned read operations')
+for t in element_types:
+    if t.name in ['Int8', 'Word8']: continue
+    print_block('''
+        primop ReadByteArrayOp_Word8As{name} "readWord8ArrayAs{name}#" GenPrimOp
+           MutableByteArray# s -> Int# -> State# s -> (# State# s, {rep_ty} #)
+           {{Read a {desc}; offset in bytes.}}
+           with has_side_effects = True
+                can_fail = True
+    ''', **t._asdict())
+
+header('aligned write operations')
+for t in element_types:
+    offset = pretty_offset(t.width)
+    print_block('''
+        primop WriteByteArrayOp_{name} "write{name}Array#" GenPrimOp
+           MutableByteArray# s -> Int# -> {rep_ty} -> State# s -> State# s
+           {{Write a {desc}; offset in {offset}.}}
+           with has_side_effects = True
+                can_fail = True
+    ''', offset = offset, **t._asdict())
+
+header('unaligned write operations')
+for t in element_types:
+    if t.name in ['Int8', 'Word8']: continue
+    print_block('''
+        primop WriteByteArrayOp_Word8As{name} "writeWord8ArrayAs{name}#" GenPrimOp
+           MutableByteArray# s -> Int# -> {rep_ty} -> State# s -> State# s
+           {{Write a {desc}; offset in bytes.}}
+           with has_side_effects = True
+                can_fail = True
+    ''', **t._asdict())
+