openMSX/doc/internal/openmsx.tex

% This is a very early openMSX design document. The general ideas remain valid
% today, but some of the details have changed. Especially the parts of the text
% that talk about implementation aspects are outdated.
%
%TODO:
% fully translate in English
% fix many(!) spelling errors
% corrections/additions


\documentclass[11pt, a4paper]{report}
\title{openMSX internals}
%Add your name here
\author{David Heremans}
\author{Wouter Vermaelen}

\begin{document}
\maketitle
\tableofcontents

\chapter{Analysis}

\section{When does a device need to be emulated}

A MSX computer has several components: a CPU, audio and video devices and
many others. All these devices need to be emulated.

In a real machine all devices work in parallel all the time. Of cource an
emulator can only emulate one device at a time. This creates some problems:

First problem, some devices need to emulated \textit{constantly}, e.g.
\begin{itemize}
\item screenrefresh by the VDP
\item soundbuffers for soundcards
\end{itemize}
We can approximate this by emulating those devices very regularly.

Second problem, devices can communicate with each other. When two emulated
devices wants to communicate we must make sure these devices have advanced
equally far in time. Example:

CPU changes by means of I/O-commands the palet settings of the VDP on
time T, therefore the VDP must calculate its screen up until time T before
the IO command is executed. From that moment on the VDP will use the new
palet data when calculating the rest of the screen.

So we need some sort of synchronization mechanism.


\section{Communication in MSX}

\subsection{General principles}

In a MSX communication happens only between the CPU and another device, never
between two non-CPUs. All communication is initiated by the CPU, except for
interupts. Communication happens at a specific moment in time but is not
instantaneous.

\subsection{(Un)predictable communication}

Communication can be either predictable or unpredictable:
\begin{itemize}
\item Predictable communication: Most interupts are predictable, example:

The VDP knows: 'if my settings remain as they are right now, I will
generate a VBLANK interrupt at time T'

\item Unpredicatble communication, examples:
	\begin{itemize}
	\item CPU executes an IO instruction
	\item CPU executes an instruction who reads from or writes to memory (!)
	\item an external interrupt (vb RS232)
	\end{itemize}
\end{itemize}

Note that \emph{most} unpredictable communication is initiated by the CPU, this is
important for some optimizations (see next chapters).


\subsection{Communication with multiple devices at once}

Important example: memory mappers (IO 0xfc \ldots 0xff).

Writing is not a problem but reading is, since the result is not defined in the MSX
standard. But some programs expect a certain behaviour\ldots


\subsection {Non-standard behaviour}

A device its memory is addressed by slot and address signals. Normally a devices
should check both these signals. Some devices (e.g.: ????) ignore slot-select
and respond whenever they see their own address.




\chapter{Design}

\section{Communication}

\subsection{Initiated by the CPU}

The CPU can read or write to a memory location or to an I/O port. The
communication happens at a specific moment in time and might take a (short) time
to complete. So besides to obvious parameters (adres/port, value) and return
values (byte read), we also need to pass and return a timestamp.


\subsection{Initiated by other device (interupts)}

\subsubsection{General}

All interupts must be planned beforehand (by synchronization points, see next
section). This is easy for predictable interupts, but impossible for
unpredictable interupts.

When a device raises an interupt it must pass control to the emulated CPU before
it can further advance in time.

\subsubsection{Unpredictable interupts}

There are two possible solutions:
\label{unpredic-irq}
\begin{enumerate}
\item Polling.
%%
Bij deze oplossing zetten we zelf de SP om de bv 50 HZ T-states.
Blijven we bij het voorbeeld van de RS232 dan betekend dat er om de 0.02 seconden
gevraagd gaat worden of er een byte klaar staat. Als dit het geval is dan kan de
ge-emuleerde RS232 zijn volgende SP plaatsten binnen bv 100 T-States en deze tijd
langzaam laten toenemen als blijkt dat er geen byte meer ontvangen is.

Methode heeft het voordeel dat je zelf een vorm van snelheid begrenzing kunt
inbouwen door een apparaat steeds maar een lage hoeveelheid interrupts te laten
genereren. Tevens zou op deze manier het mogelijk eenvoudiger zijn om bv een
RS232 connectie te faken aan de hand van een file met een 'opgenomen' connectie.
Bij beide methodes moet het device er voor zorgen dat het er rekening mee houd
dat een geregistreerd SP wel eens tijdens een DI zou kunnen vallen en dat daarom
een gesette interrupt niet noodzakelijker wijze word afgehandeld. Dit wil
zeggen, er kunnen bv drie SP geregistreerd worden die elk een setInterrupt()
uitvoeren maar dat slechts na de derde setInterrupt de CPU deze pas afhandeld!.

\item Converting van Guest OS interrupts naar MSX interrupts
Het zou ook mogelijk zijn om als het guest OS een interrupt krijgt dat deze kan
ingelast worden in de datastructuur met de SP, aangezien deze al in staat is om
SP's tussen te lassen in de bestaande structuur zou dit geen probleem zijn.
\end{enumerate}


\subsection{Communication with multiple devices at once}

Most important example: memory mappers (IO 0xfc \ldots 0xff)

%%
For this kind of behaviour the most usefull principle would be a master-slave approach
In het geval van memmorymappers heb ik dit als volgt reeds geprogrammeert:
\begin{itemize}
\item De classe MSXMemMapDriver(=master) registreerd zich bij het MSXMotherboard voor de
poorten OxFC .. 0xFF.
\item De Driver houd per slot/sublsot bij wat de mappergrootte is. Tijdens de initfase
vervangt de MapperDriver alle verwijzingen naar hem in de slotstructuur door verwijzingen
naar verschillende MemMapSlaves.
\item Bij OUT activiteit zal de driver de gepaste slaves vertellen dat ze nu data moeten
lezen/schrijven op andere plaatsen in mapper van hun main-/sub-slot combinatie.
\item Bij IN activiteit is het de mapper die de waarden kent en de juiste value aan de
CPU terug geeft. Op deze manier is het simpel om de pull-up van de Turbo-R te
emuleren, of de conflicten van het lezen van meerdere mappers in de driver te
implementeren.
\end{itemize}

%%
Dit idee ga ik waarschijnlijk ook gebruiken bij de CPU, op die manier heb je een
CPU-master en twee CPU-slaves bij de turbo R. De master zal zich dan ook registreren
bij het MotherBoard om zo op de CPU-switch poort- van de Turbo-R te kunnen luisteren
en de juiste taakdelegatie te kunnen doen.



\section{Synchronization}

\subsection{Time-active and time-passive devices}

\subsubsection{Time-active devices}
This are devices that can request to be emulated at a future moment in time,
such a moment is called a \emph{synchronization point}. The reasons for such a request
are:
\begin{itemize}
\item Some devices need to be emulated regularly, e.g.:
	\begin{itemize}
	%%
	\item VDP moet regelmatig zorgen voor beeldopbouw
	\item soundchips moeten regelmatig nieuwe samples klaarzetten
	\end{itemize}
\item Some devices can raise an IRQ, these IRQ must be announced beforehand
with a synchronization point. This is easy for predictable IRQ's, but must be
estimated for unpreditable IRQ's (see section \ref{unpredic-irq}).
\end{itemize}

\subsubsection{Time-passive devices}
These devices can be emulated at the moment the CPU tries to communicate with
it. Example:
\begin{itemize}
\item Keyboard
\item RAM/ROM
\end{itemize}


\subsection{Scheduler algorithm}

A few rules:
\begin{enumerate}
\item %%
geen enkel device mag in uitvoering 'voorliggen' op de CPU.
Dit omdat praktisch alle onvoorspelbare communicate (IO en memory) uitgaat
van de CPU. Als een device op een bepaald moment voorligt op de CPU en als
nadien de CPU tijdens zijn 'inhaalbeweging' communiceerd met dat device, ...
ja dan klopt er iets niet.

\item %%
elk device moet zijn eerstvolgende synchronisatie punt
aan de scheduler melden.
\end{enumerate}

Now the algorithm:
\begin{enumerate}
%%
\item De scheduler neemt het vroegste synchronisatie punt, en \textit{probeert}
de CPU tot op dat punt te brengen.
\item Als dit lukt
	\begin{enumerate}
	%%
	\item \label{alg:ok}
	dan wordt ook het device dat dit synchronisatie punt had gezet tot
	hier gebracht (dit lukt altijd)
	\item \label{alg:nok}
	als het niet lukt (CPU heeft een IO of een memory instructie
	uitgevoerd). Dan wordt eerst het device waarmee gecommuniceerd
	werd bijgebracht (nu niet volledig tot aan synchronisatie punt, maar tot
	waar de CPU gekomen was) en dan wordt pas de IO of memory opdracht
	uitgevoerd. Het zou kunnen dat het device een (nieuw, vroeger)
	synchronisatie punt heeft gezet, dus het algoritme begint weer van
	vanvoor.
	\end{enumerate}
\end{enumerate}

Note a device may not register a new SP that comes in time before the CPU's
current time. (Step \ref{alg:ok}, \ref{alg:nok})




\chapter{Implementation}

\section{Timetracking}

Every device has its own native clock frequency, for the emulation of one
particular device it is easy to work with native T-states. But for the
global emulator it is easier to work with some least-common-multiple frequency.

The class 'Emutime' offers such an interface: devices work with native T-states,
but they are internally converted to global emulator T-states.

All operations involving time should go through this class.


\section{The implementation of the scheduler in openMSX}

The MSXScheduler will keep track of the T-states. This 'scheduler'-devices
is 'owned' by the MSXMotherBoard. The MSXScheduler is a generic object
that can be reused by other devices. If for example someone would like to
make the VDP as a collection of internal devices each withs it's own
function and needs some internal scheduler ...

\subsection{Scheduler and timetracking}

The MSXScheduler keeps a simple list for timescheduling. This is a simple
list of the next SP and the device that has set this SP. The list is
ordered so that the first element always is the first SP that has to
reached.  The scheduler will follow this simple procedure:
\begin{enumerate}
\item Set the target T-State of the cpu to the first SP in the list.
\item Let the CPU execute until the target T-state.
\item Get the device from the first SP in the list and let it reach its
T-state.
\item Remove the first elemnt from the list
\item Goto step 1
\end{enumerate}

Attention. The first element of the list in step 1 could be different from
the first element in step 3. This is because of the fact that during step
2 the device can do some I/O to other device who can set a new SP that has
a smaller value then the set target T-state. For example, enabling
line-interrupts from the VDP could change the first SP to be reached.  For
this reasson the scheduler, when inserting a list element before the first
element, will call the setTargetTStates of the CPU. this will garuantee
that the CPU will execute until the first SP element of the list.

Note 1: To get the extra time-info during communication between CPU and
devices the calls (readMem,writeMem,readIO and writeIO) pas as their
latest parameter the current T-state of the CPU. This makes it possible
for devices to "catch up" with the processor if needed. So the graph of
Wouter could be implicetly included in the emulation by passing
the current time around during device communication.
Note 2: Also non-msx devices could be integrated in this list. for example
the routine that draw the actual screen on your PC could be called from
the scheduler. Also you could make a sort of dummy device that would be
called each 1/50 second and would block emulation until there is really
1/50 second past between it's previous execution and the current one.

\subsection{Device Sync points}

Since each device has its own natural clockfrequency the scheduler will
run at the speed of the lowest common multiple. In case of an MSX2 the CPU
is at 3.5 MHz, the VDP runs at 21 MHz. Therefore the scheduler runs at 21
MHz.

However we could make a MSXDevice that uses a clockfrequency of 42 MHz. In
this case the scheduler will need run at 42 MHz, however the CPU still
needs to run at 3.5 MHz and not at 7 MHz. To overcomme this problem the
scheduler has a method called getTimeMultiplier(nativeFreq). You can pass
your native frequency and it will tell you by how much you need to
multiply the devices native T-states to get to the frequency of the
scheduler.

In the first case this would result in the value 6, in the 42MHz case this
would return 12. If you ask the scheduler for the current T-state you will
need to divide them by this value to get to the native T-state value

The most used SP setting is from "now" until x T-states later. This can be
achieved using the method setLaterSP(getTimeMultiplier(nativeFreq) *
numberOfNativeTStatesLater , this ).


\section{For interrupts itself}

If a device generates an interrupt it should call the
MSXMotherboard.raiseIRQ() method. when a device doesn't activate
the interrupt line any longer it will call the
MSXMotherboard.lowerIRQ(). The emulate CPU will after each
instruction check the IRQ-line and respond accordingly (EI/DI,
interruptmode,...).  In the Motherboard the IRQ-line will be
implemented using a counter, if irq-counter is zero then no
interrupts otherwise the irq-counter should contain the number of
devices that are generating an IRQ.

\emph{A device isn't allowed to call the raise(lower)irq twice in a row!!}

The MSXDevice classe contains a standard method setInterrupt() and
resetInterrupt() which take care of this restriction and call the
MSXMotherBoard if needed.

We could make it mandatory to set the interrupt as an SP. In this way we
would only need to test if the IRQ-line is active each time we call the
CPU from the scheduler. However for most devices this wouldn't change
anything, they still need to emulate up until the SP point and call the
raiseIRQ(). Any comments ??

\chapter{Implementing devices for openMSX}
Before you start implementing a new device for openMSX make sure you have read and understand the way openMSX handles eumTime. If your device is able to generate an IRQ you must follow the rules described above.

\section{The life cycle of an MSXDevice}

\subsection{In the beginning}
In the beginning there was nothing....
And then a lot of things happened and after a few billion yeas it all resulted in openMSX. And internally in openMSX also a lot of things need to happen before you get a running emulator.
This is what happens before a device becomes aware of its existance.
\begin{itemize}
\item The main loop creates an MSXConfig object and let it parse a configuration file.
\item A MSXMotherBoard is create, this object can be viewed as the bus of the MSX and keep tracks of all the devices and slot layouts.
\item The devicefactory creates the objects that are indicate by the MSXConfig object. It loops trough the objects that are summed up in the configuration, each time creating an object of the indicated class and adding to the deviceslist of the motherboard. Each MSXDevice also gets a pointer set towards it personal configuration object. For people who need a more vivid description of what has happended up until now: We just create all the needed chips and PCB's and tossed them all on a big pile.
\end{itemize}


The life cycle of an MSXdevice follows the following basic steps
\begin{itemize}
\item Object is instantiated
\item The device reads its configuration and prepares itself to run
\item The device waits for calls made by the scheduler/CPU.
\item When destroyed the object nicely releases it sources.
\end{itemize}

\subsection{Instantiation}
The life cycle starts with the birth of the object.
During this constructor fase the MSXDevice can set some of its internal parameters to default values. The general rule being that this initialisation must be fail-proof. Meaning that during this initialization we can not try to malloc some memory or read a file or something else that could go hay-wire. By following this simple rule we can safely asume that the device factory can contruct all of the desired devices with out bailing out.
If we need to bail out this will result in the termination of the entire emulator. If for instance the total system memory isn't enough to even create an object.

\subsection{Initialization}
Alsmost imediately after the device is instantiated, the first method that will be called is the setConfigDevice(MSXConfig::Device*). This will allow the MSXDevice to read its own configuration during the following initialization. Remember that the instantiation should be simple and fail-safe. Now it is time to begin the more dangerous internal set up. At this point all needed devices are instantiated, only there configuration isn't complete yet. Now the motherboard start calling the init() method of all of it's known devices.
Know you can try to read files, allocated memory and (since all devices are existing) trying some initial communication with other MSXDevices. Be aware howver that this device itself may not have yet been initialized.

During the initialisation the device should register its place in the slot structure with the MSXMotherBoard. Also registering I/O ports is done at this point.

One of the reasons to have this method seperate from the instatiation is the fact that later on we could decide that each device should be able to be re-initialized during run time. It would be advicable to write your code so that this is possible. For pointers this would mean that the contructor makes them NULL pointers and that the init should check if the pointers is empty before trying the malloc, and constructs such a like.

\subsection{Start}
One of the first things the device should do in his start method is asking the motherboard for the actual emutime. Remember that it should be possible to insert a device during the emulation. So it isn't smart to assume that the start method will be called when emutime is still zero. This is ofcourse only needed if the device uses time \^\_\^
During this start the device sould also set it's synchronisation points if needed. ex. a VDP should register it's first following interrupt.

\subsection{Stop}
\subsection{Reset}


Remark 1 : creating of MSXDevices
---------------------------------
the sequence in which MSXDevices are used is as follows
--if <slotted> are embeded in the <device>-block this device will be visible in the slotstructure of the emulated MSX.Multiple <slotted>blocks are possible f.e. a simple 64KB RAM expansion is visible in one slot,one subslot and the 4 pages of it.
--the< parameter> block is parsed and every key,value pair is passed to the setParameter methode. This method is used to set internal parameters of the MSXDevice, f.e. the amount of vram could be passed to a VDPdevice, or the number of mapper pages for a MemMapper.
-once athe configuration file is parsed and all devices created, all devices in the deviceslist have their init() method called. In the init() method the devices can allocate desired memmory, register I/O ports using the register\_IO\_Ini/IO\_Out method of the MSXMotherBoard.
-at last the virtual MSX is started, the motherboard sends a reeset signal to all devices and starts emulating, if the user requests a reset, the reset method is called for all devices and the MSX comenses al over. The reset method is used for warm-boot, so for example memory should NOT be cleared from most memory devices.





\end{document}