VDPVRAM.hh

Go to the documentation of this file.

#ifndef VDPVRAM_HH
#define VDPVRAM_HH
 
#include "VRAMObserver.hh"
#include "VDP.hh"
#include "VDPCmdEngine.hh"
#include "SimpleDebuggable.hh"
#include "Ram.hh"
#include "Math.hh"
#include "openmsx.hh"
#include <cassert>
 
namespace openmsx {
 
class DisplayMode;
class SpriteChecker;
class Renderer;
 
/*
Note: The way VRAM is accessed depends a lot on who is doing the accessing.
 
For example, the ranges:
- Table access is done using masks.
- Command engine work areas are rectangles.
- CPU access always spans full memory.
 
Maybe define an interface with multiple subclasses?
Or is that too much of a performance hit?
If accessed through the interface, a virtual method call is made.
But invoking the objects directly should be inlined.
 
Timing:
 
Each window reflects the state of the VRAM at a specified moment in time.
 
Because the CPU has full-range write access, it is incorrect for any window
to be ahead in time compared to the CPU. Because multi-cycle operations are
implemented as atomic, it is currently possible that a window which starts
an operation slightly before CPU time ends up slightly after CPU time.
Solutions:
- break up operations in 1-cycle suboperations
  (very hard to reverse engineer accurately)
- do not start an operation until its end time is after CPU time
  (requires minor rewrite of command engine)
- make the code that uses the timestamps resilient to after-CPU times
  (current implementation; investigate if this is correct)
 
Window ranges are not at fixed. But they can only be changed by the CPU, so
they are fixed until CPU time, which subsystems will never go beyond anyway.
 
The only two subsystems with write access are CPU and command engine.
The command engine can only start executing a new command if instructed so
by the CPU. Therefore it is known which area the command engine can write
in until CPU time:
- empty, if the command engine is not executing a command
- the command's reach, if the command engine is executing a command
Currently the command's reach is not computed: full VRAM is used.
Taking the Y coordinate into account would speed things up a lot, because
usually commands execute on invisible pages, so the number of area overlaps
between renderer and command engine would be reduced significantly.
Also sprite tables are usually not written by commands.
 
Reading through a window is done as follows:
A subsystem reads the VRAM because it is updating itself to a certain moment
in time T.
1. the subsystems syncs the window to T
2. VDPVRAM checks overlap of the window with the command write area
   no overlap -> go to step 6
3. VDPVRAM syncs the command engine to T
4. the command engine calls VDPVRAM to write each byte it changes in VRAM,
   call the times this happens C1, C2, C3...
5. at the n-th write, VDPVRAM updates any subsystem with the written address
   in its window to Cn, this can include the original subsystem
6. the window has reached T
   now the subsystem can update itself to T
Using this approach instead of syncing on read makes sure there is no
re-entrance on the subsystem update methods.
 
Note: command engine reads through write window when doing logic-ops.
So "source window" and "destination window" would be better names.
 
Interesting observation:
Each window is at the same moment in time as the command engine (C):
- if a window doesn't overlap with the command destination window, it is
  stable from a moment before C until the CPU time T
- if a window overlaps with the command destination window, it cannot be
  before C (incorrect) or after C (uncertainty)
Since there is only one time for the entire VRAM, the VRAM itself can be said
to be at C. This is a justification for having the sync method in VDPVRAM
instead of in Window.
 
Writing through a window is done as follows:
- CPU write: sync with all non-CPU windows, including command engine write
- command engine write: sync with non-CPU and non-command engine windows
Syncing with a window is only necessary if the write falls into that window.
 
If all non-CPU windows are disjunct, then all subsystems function
independently (at least until CPU time), no need for syncs.
So what is interesting, is which windows overlap.
Since windows change position infrequently, it may be beneficial to
precalculate overlaps.
Not necessarily though, because even if two windows overlap, a single write
may not be inside the other window. So precalculated overlaps only speeds up
in the case there is no overlap.
Maybe it's not necessary to know exactly which windows overlap with cmdWrite,
only to know whether there are any. If not, sync can be skipped.
 
Is it possible to read multiple bytes at the same time?
In other words, get a pointer to an array instead of reading single bytes.
Yes, but only the first 64 bytes are guaranteed to be correct, because that
is the granularity of the color table.
But since whatever is reading the VRAM knows what it is operating on, it
can decide for itself how many bytes to read.
 
*/
 
class DummyVRAMObserver final : public VRAMObserver
{
public:
        void updateVRAM(unsigned /*offset*/, EmuTime::param /*time*/) override {}
        void updateWindow(bool /*enabled*/, EmuTime::param /*time*/) override {}
};
 
class VRAMWindow
{
public:
        VRAMWindow(const VRAMWindow&) = delete;
        VRAMWindow& operator=(const VRAMWindow&) = delete;
 
        [[nodiscard]] inline unsigned getMask() const {
                assert(isEnabled());
                return effectiveBaseMask;
        }
 
        inline void setMask(unsigned newBaseMask, unsigned newIndexMask,
                            unsigned newSizeMask, EmuTime::param time) {
                origBaseMask = newBaseMask;
                newBaseMask &= newSizeMask;
                if (isEnabled() &&
                    (newBaseMask  == effectiveBaseMask) &&
                    (newIndexMask == indexMask)) {
                        return;
                }
                observer->updateWindow(true, time);
                effectiveBaseMask = newBaseMask;
                indexMask         = newIndexMask;
                baseAddr  =  effectiveBaseMask & indexMask; // this enables window
                combiMask = ~effectiveBaseMask | indexMask;
        }
 
        inline void setMask(unsigned newBaseMask, unsigned newIndexMask,
                            EmuTime::param time) {
                setMask(newBaseMask, newIndexMask, sizeMask, time);
        }
 
        inline void disable(EmuTime::param time) {
                observer->updateWindow(false, time);
                baseAddr = unsigned(-1);
        }
 
        [[nodiscard]] inline bool isContinuous(unsigned index, unsigned size) const {
                assert(isEnabled());
                unsigned endIndex = index + size - 1;
                unsigned areaBits = Math::floodRight(index ^ endIndex);
                if ((areaBits & effectiveBaseMask) != areaBits) return false;
                if ((areaBits & ~indexMask)        != areaBits) return false;
                return true;
        }
 
        [[nodiscard]] inline bool isContinuous(unsigned mask) const {
                assert(isEnabled());
                assert((mask & ~indexMask)        == mask);
                return (mask & effectiveBaseMask) == mask;
        }
 
        template<size_t size>
        [[nodiscard]] inline std::span<const byte, size> getReadArea(unsigned index) const {
                assert(isContinuous(index, size));
                return std::span<const byte, size>{
                                &data[effectiveBaseMask & (indexMask | index)],
                                size};
        }
 
        template<size_t size>
        [[nodiscard]] inline std::pair<std::span<const byte, size / 2>, std::span<const byte, size / 2>>
                        getReadAreaPlanar(unsigned index) const {
                assert((index & 1) == 0);
                assert((size & 1) == 0);
                unsigned endIndex = index + size - 1;
                unsigned areaBits = Math::floodRight(index ^ endIndex);
                areaBits = ((areaBits << 16) | (areaBits >> 1)) & 0x1FFFF & sizeMask;
                (void)areaBits;
                assert((areaBits & effectiveBaseMask) == areaBits);
                assert((areaBits & ~indexMask)        == areaBits);
                assert(isEnabled());
                unsigned addr = effectiveBaseMask & (indexMask | (index >> 1));
                const byte* ptr0 = &data[addr | 0x00000];
                const byte* ptr1 = &data[addr | 0x10000];
                return {std::span<const byte, size / 2>{ptr0, size / 2},
                        std::span<const byte, size / 2>{ptr1, size / 2}};
        }
 
        [[nodiscard]] inline byte readNP(unsigned index) const {
                assert(isEnabled());
                return data[effectiveBaseMask & index];
        }
 
        [[nodiscard]] inline byte readPlanar(unsigned index) const {
                assert(isEnabled());
                index = ((index & 1) << 16) | ((index & 0x1FFFE) >> 1);
                unsigned addr = effectiveBaseMask & index;
                return data[addr];
        }
 
        [[nodiscard]] inline bool hasObserver() const {
                return observer != &dummyObserver;
        }
 
        inline void setObserver(VRAMObserver* newObserver) {
                observer = newObserver;
        }
 
        inline void resetObserver() {
                observer = &dummyObserver;
        }
 
        [[nodiscard]] inline bool isInside(unsigned address) const {
                return (address & combiMask) == baseAddr;
        }
 
        inline void notify(unsigned address, EmuTime::param time) {
                if (isInside(address)) {
                        observer->updateVRAM(address - baseAddr, time);
                }
        }
 
        void setSizeMask(unsigned newSizeMask, EmuTime::param time) {
                if (isEnabled()) {
                        setMask(origBaseMask, indexMask, newSizeMask, time);
                }
                // only apply sizeMask after observers have been notified
                sizeMask = newSizeMask;
        }
 
        template<typename Archive>
        void serialize(Archive& ar, unsigned version);
 
private:
        [[nodiscard]] inline bool isEnabled() const {
                return baseAddr != unsigned(-1);
        }
 
private:
        friend class VDPVRAM;
 
        explicit VRAMWindow(Ram& vram);
 
        byte* data;
 
        VRAMObserver* observer = &dummyObserver;
 
        unsigned origBaseMask = 0;
 
        unsigned effectiveBaseMask = 0;
 
        unsigned indexMask = 0;
 
        unsigned baseAddr = unsigned(-1); // disable window
 
        unsigned combiMask = 0;
 
        unsigned sizeMask;
 
        static inline DummyVRAMObserver dummyObserver;
};
 
class VDPVRAM
{
public:
        VDPVRAM(const VDPVRAM&) = delete;
        VDPVRAM& operator=(const VDPVRAM&) = delete;
 
        VDPVRAM(VDP& vdp, unsigned size, EmuTime::param time);
 
        void clear();
 
        inline void sync(EmuTime::param time) {
                assert(vdp.isInsideFrame(time));
                cmdEngine->sync(time);
        }
 
        inline void cmdWrite(unsigned address, byte value, EmuTime::param time) {
                #ifdef DEBUG
                // Rewriting history is not allowed.
                assert(time >= vramTime);
                #endif
                assert(vdp.isInsideFrame(time));
 
                // handle mirroring and non-present ram chips
                address &= sizeMask;
                if (address >= actualSize) [[unlikely]] {
                        // 192kb vram is mirroring is handled elsewhere
                        assert(address < 0x30000);
                        // only happens in case of 16kb vram while you write
                        // to range [0x4000,0x8000)
                        return;
                }
 
                writeCommon(address, value, time);
        }
 
        inline void cpuWrite(unsigned address, byte value, EmuTime::param time) {
                #ifdef DEBUG
                // Rewriting history is not allowed.
                assert(time >= vramTime);
                #endif
                assert(vdp.isInsideFrame(time));
 
                // handle mirroring and non-present ram chips
                address &= sizeMask;
                if (address >= actualSize) [[unlikely]] {
                        // 192kb vram is mirroring is handled elsewhere
                        assert(address < 0x30000);
                        // only happens in case of 16kb vram while you write
                        // to range [0x4000,0x8000)
                        return;
                }
 
                // We should still sync with cmdEngine, even if the VRAM already
                // contains the value we're about to write (e.g. it's possible
                // syncing with cmdEngine changes that value, and this write
                // restores it again). This fixes bug:
                //   [2844043] Hinotori - Firebird small graphics corruption
                if (cmdReadWindow .isInside(address) ||
                    cmdWriteWindow.isInside(address)) {
                        cmdEngine->sync(time);
                }
                writeCommon(address, value, time);
 
                cmdEngine->stealAccessSlot(time);
        }
 
        [[nodiscard]] inline byte cpuRead(unsigned address, EmuTime::param time) {
                #ifdef DEBUG
                // VRAM should never get ahead of CPU.
                assert(time >= vramTime);
                #endif
                assert(vdp.isInsideFrame(time));
 
                address &= sizeMask;
                if (cmdWriteWindow.isInside(address)) {
                        cmdEngine->sync(time);
                }
                cmdEngine->stealAccessSlot(time);
 
                #ifdef DEBUG
                vramTime = time;
                #endif
                return data[address];
        }
 
        void updateDisplayMode(DisplayMode mode, bool cmdBit, EmuTime::param time);
 
        void updateDisplayEnabled(bool enabled, EmuTime::param time);
 
        void updateSpritesEnabled(bool enabled, EmuTime::param time);
 
        void updateVRMode(bool mode, EmuTime::param time);
 
        void setRenderer(Renderer* renderer, EmuTime::param time);
 
        [[nodiscard]] unsigned getSize() const {
                return actualSize;
        }
 
        inline void setSpriteChecker(SpriteChecker* newSpriteChecker) {
                spriteChecker = newSpriteChecker;
        }
 
        inline void setCmdEngine(VDPCmdEngine* newCmdEngine) {
                cmdEngine = newCmdEngine;
        }
 
        void change4k8kMapping(bool mapping8k);
 
        template<typename Archive>
        void serialize(Archive& ar, unsigned version);
 
private:
        /* Common code of cmdWrite() and cpuWrite()
         */
        inline void writeCommon(unsigned address, byte value, EmuTime::param time) {
                #ifdef DEBUG
                assert(time >= vramTime);
                vramTime = time;
                #endif
 
                // Check that VRAM will actually be changed.
                // A lot of costly syncs can be saved if the same value is written.
                // For example Penguin Adventure always uploads the whole frame,
                // even if it is the same as the previous frame.
                if (data[address] == value) return;
 
                // Subsystem synchronisation should happen before the commit,
                // to be able to draw backlog using old state.
                bitmapVisibleWindow.notify(address, time);
                spriteAttribTable.notify(address, time);
                spritePatternTable.notify(address, time);
 
                data[address] = value;
 
                // Cache dirty marking should happen after the commit,
                // otherwise the cache could be re-validated based on old state.
 
                // these two seem to be unused
                // bitmapCacheWindow.notify(address, time);
                // nameTable.notify(address, time);
                assert(!bitmapCacheWindow.hasObserver());
                assert(!nameTable.hasObserver());
 
                // in the past GLRasterizer observed these two, now there are none
                assert(!colorTable.hasObserver());
                assert(!patternTable.hasObserver());
 
                /* TODO:
                There seems to be a significant difference between subsystem sync
                and cache admin. One example is the code above, the other is
                updateWindow, where subsystem sync is interested in windows that
                were enabled before (new state doesn't matter), while cache admin
                is interested in windows that become enabled (old state doesn't
                matter).
                Does this mean it makes sense to have separate VRAMWindow like
                classes for each category?
                Note: In the future, sprites may switch category, or fall in both.
                */
        }
 
        void setSizeMask(EmuTime::param time);
 
private:
        VDP& vdp;
 
        Ram data;
 
        class LogicalVRAMDebuggable final : public SimpleDebuggable {
        public:
                explicit LogicalVRAMDebuggable(VDP& vdp);
                [[nodiscard]] byte read(unsigned address, EmuTime::param time) override;
                void write(unsigned address, byte value, EmuTime::param time) override;
        private:
                unsigned transform(unsigned address);
        } logicalVRAMDebug;
 
        struct PhysicalVRAMDebuggable final : SimpleDebuggable {
                PhysicalVRAMDebuggable(VDP& vdp, unsigned actualSize);
                [[nodiscard]] byte read(unsigned address, EmuTime::param time) override;
                void write(unsigned address, byte value, EmuTime::param time) override;
        } physicalVRAMDebug;
 
        // TODO: Renderer field can be removed, if updateDisplayMode
        //       and updateDisplayEnabled are moved back to VDP.
        //       Is that a good idea?
        Renderer* renderer;
 
        VDPCmdEngine* cmdEngine;
        SpriteChecker* spriteChecker;
 
        #ifdef DEBUG
        EmuTime vramTime;
        #endif
 
        unsigned sizeMask;
 
        const unsigned actualSize;
 
        bool vrMode;
 
public:
        VRAMWindow cmdReadWindow;
        VRAMWindow cmdWriteWindow;
        VRAMWindow nameTable;
        VRAMWindow colorTable;
        VRAMWindow patternTable;
        VRAMWindow bitmapVisibleWindow;
        VRAMWindow bitmapCacheWindow;
        VRAMWindow spriteAttribTable;
        VRAMWindow spritePatternTable;
};
 
} // namespace openmsx
 
#endif