//---------------------------------------------------------------------------//
//  1100101 |_ mov #0, r4         __                                         //
//     11   |_ <0xb380 %5c4>     / _|_ _____ ___                             //
//     0110 |_ 3.50 -> 3.60     |  _\ \ / _ (_-<                             //
//          |_ base# + offset   |_| /_\_\___/__/                             //
//---------------------------------------------------------------------------//
// fxos/AbstractMemory: Simulated memory
//
// This header defines the typeclass for simulated memory within a 32-bit
// address space. The class provides functions to identify the simulated range
// within the address space, as well as basic read and search operations.
//
// Suclasses of this only need to implement the translate_dynamic() method
// which gives low-level access to part of the simulated memory.
//
// Note that currently, given the implementation of virtual space bindings and
// AbstractMemory methods, most operations only try to translate_dynamic()
// once -- which means that they fail if the requested range is not simulated
// in a single block. This is usually not a problem because virtual space
// bindings simulate small memory areas separated by huge gaps, so they never
// extend each other.
//---

#ifndef FXOS_ABSTRACTMEMORY_H
#define FXOS_ABSTRACTMEMORY_H

#include <fxos/memory.h>
#include <fxos/util/Addressable.h>
#include <cstdint>

namespace FxOS {

/* A common interface for simulated memory. All non-virtual methods are
    provided by the base class and need not be implemented. */
class AbstractMemory
{
public:
    /* Checks if an address or interval is simulated (in its entirety) */
    bool covers(uint32_t addr, int size=1);

    /* Check if a full region is simulated */
    bool covers(MemoryRegion const &region);

    /* Returns the data located at the provided virtual address, nullptr if it
       is not entirely covered. */
    char const *translate(uint32_t addr, int size=1);

    /* Returns the data located at the provided virtual address, and indicates
       how much is available in *size. The pointer is null if [addr] itself is
       not covered, in which case *size is also set to 0. */
    virtual char const *translate_dynamic(uint32_t addr, int *size) = 0;

    /* Search a binary pattern in the specified area. Returns the virtual
       address of the first occurrence if any is found, [end] otherwise
       (including if the range is empty or exceeds simulated memory). */
    uint32_t search(uint32_t start, uint32_t end, void const *pat, int size);

    /* Read a simple object from memory. The following methods all assume that
       the specified address is simulated, and return a default value if it's
       not -- you should probably check beforehand! Alignment constraints are
       not checked either, that's up to you.

       The return type has the value in [.value] and remembers the address in
       [.address], which is sometimes useful. It implicitly converts to the
       data type, see <fxos/util/Addressable.h>. */

    /* Various sizes of integers with sign-extension or zero-extension. */
    Addressable<int8_t>   read_i8 (uint32_t addr);
    Addressable<uint8_t>  read_u8 (uint32_t addr);
    Addressable<int16_t>  read_i16(uint32_t addr);
    Addressable<uint16_t> read_u16(uint32_t addr);
    Addressable<int32_t>  read_i32(uint32_t addr);
    Addressable<uint32_t> read_u32(uint32_t addr);

    /* Read a non-NUL-terminated string */
    Addressable<std::string> read_str(uint32_t addr, size_t len);
};

} /* namespace FxOS */

#endif /* FXOS_ABSTRACTMEMORY_H */