qute

  1-- SPDX-FileCopyrightText: 2023-2024 University of Bremen
  2-- SPDX-FileCopyrightText: 2025 Sören Tempel <soeren+git@soeren-tempel.net>
  3--
  4-- SPDX-License-Identifier: MIT AND GPL-3.0-only
  5
  6-- | This module provides an implementation of a simple byte-addressable memory
  7-- based on "Data.Array".
  8module Language.QBE.Simulator.Memory
  9  ( -- * Type Aliases
 10    Address,
 11    Size,
 12    showAddr,
 13
 14    -- * Value Representation
 15    Storable (toBytes, fromBytes),
 16
 17    -- * Memory Representation
 18    Memory,
 19    mkMemory,
 20    memSize,
 21    loadBytes,
 22    storeBytes,
 23
 24    -- * Memory Address
 25    toMemAddr,
 26    addrOverlap,
 27    alignAddr,
 28  )
 29where
 30
 31import Data.Array.IO
 32  ( MArray,
 33    getBounds,
 34    newArray_,
 35    readArray,
 36    writeArray,
 37  )
 38import Data.Bits (complement, (.&.))
 39import Data.Word (Word64)
 40import Language.QBE.Types qualified as QBE
 41import Numeric (showHex)
 42
 43-- | Type used to represent an address in memory.
 44type Address = Word64
 45
 46-- | Type used to represent the memory's size.
 47type Size = Word64
 48
 49-- | Represent an address as a hexadecimal string.
 50showAddr :: Address -> String
 51showAddr addr = "0x" ++ showHex addr ""
 52
 53------------------------------------------------------------------------
 54
 55-- | Type class for types that can be stored in memory. That is, types whose
 56-- values can be converted to the given byte representation and vice versa.
 57class Storable valTy byteTy where
 58  -- | Convert a value type to a list of byte types.
 59  toBytes :: valTy -> [byteTy]
 60
 61  -- | Convert a list of bytes to a value type of 'QBE.LoadType'. Returns
 62  -- 'Nothing' if the length of the list is incompatible with the given
 63  -- 'QBE.LoadType'.
 64  fromBytes :: QBE.LoadType -> [byteTy] -> Maybe valTy
 65
 66-- | Memory parameterized over the Array type (e.g. 'Data.Array.IO.IOUArray')
 67-- and a byte polymorphic representation (e.g. 'Data.Word.Word8').
 68data Memory a v = Memory
 69  { memStart :: Address,
 70    memBytes :: a Address v
 71  }
 72
 73-- | Create a new t'Memory' which starts at the given base address and
 74-- has a maximum capacity (i.e., can store up to the given amount of bytes).
 75-- The memory is not initialized, reading an uninitialized values results
 76-- in an error.
 77mkMemory :: (MArray t a IO) => Address -> Size -> IO (Memory t a)
 78mkMemory startAddr size = do
 79  ary <- newArray_ (0, size - 1)
 80  return $ Memory startAddr ary
 81
 82-- | Translate global address to a memory-local address. That is, performs
 83-- address translation relative to the base address of the t'Memory'.
 84toMemAddr :: Memory t a -> Address -> Address
 85toMemAddr mem addr = addr - memStart mem
 86
 87-- | Returns true if the given addresses, passed in the first and second
 88-- argument, overlap in the given range (i.e., the given amount of bytes).
 89addrOverlap :: Address -> Address -> Size -> Bool
 90addrOverlap addr1 addr2 range =
 91  addr1 < endAddr addr2 && endAddr addr1 > addr2
 92  where
 93    endAddr :: Address -> Address
 94    endAddr a = a + range
 95
 96-- | Align an address upwards for the given alignment.
 97alignAddr :: Address -> Size -> Address
 98alignAddr addr align = (addr + (align - 1)) .&. complement (align - 1)
 99
100-- | Returns the size of the memory in bytes.
101memSize :: (MArray t a IO) => Memory t a -> IO Size
102memSize = fmap ((+ 1) . snd) . getBounds . memBytes
103
104-- | Write the list of bytes to memory at the given address.
105storeBytes :: (MArray t a IO) => Memory t a -> Address -> [a] -> IO ()
106storeBytes mem addr bytes =
107  mapM_ (\(off, val) -> storeByte mem (addr + off) val) $
108    zip [0 ..] bytes
109  where
110    storeByte :: (MArray t a IO) => Memory t a -> Address -> a -> IO ()
111    storeByte m a = writeArray (memBytes m) $ toMemAddr mem a
112{-# INLINEABLE storeBytes #-}
113
114-- | Load the given amount of bytes at the given address.
115loadBytes :: (MArray t a IO) => Memory t a -> Address -> Size -> IO [a]
116loadBytes mem addr byteSize =
117  mapM (\off -> loadByte mem (addr + off)) [0 .. byteSize - 1]
118  where
119    loadByte :: (MArray t a IO) => Memory t a -> Address -> IO a
120    loadByte m = readArray (memBytes m) . toMemAddr m
121{-# INLINEABLE loadBytes #-}