-
Notifications
You must be signed in to change notification settings - Fork 8
4. Understand the MiSTer core
Before you start porting, you should first understand how the MiSTer core
works for an end-user. In the optimal case, you own a MiSTer and can actually
experiment and play with the core. But this is not mandatory. There are also a
lot of YouTube videos about many cores. It is important that you get an
overall "feeling" for the core and how it behaves. And even more important:
About the disk mounting, ROM loading and configuration options that are
available to the end user, because this helps you to understand a lot of
things, including MiSTer's core configuration string (CONF_STR
). The core
configuration string is used to generate the menu shown to the end-user
(similar to M2M's OSM) and therefore CONF_STR
is paramount to understanding
many of the parameters, wiring and default values that the core needs to run.
So you have played enough with the core and/or watched some YouTube videos and you feel you have understood the "end user view" of the MiSTer core you want to port to MEGA65? Great - then let's start to dive in at the deep end.
MiSTer has an excellent documentation for developers where you can learn how to port a core TO MiSTer. What we want to achieve here is learn how to port a core FROM MiSTer. Nevertheless your MiSTer2MEGA65 porting experience will be much smoother if you start from first principles. Please read the following chapters of the MiSTer documentation before you proceeed:
- Porting Cores
- Core Configuration String
- Overview of emu module
- sys - hps_io
- sys - video_freak
- sys - video_mixer
- sys - arcade_video
Don't worry if you are not understanding everything written in these seven chapters. It is more important that you have a high-level overview of the concepts and that you have seen most of them now at least once and that you know where to look in case you get stuck at a later stage of your porting adventure.
Now it is time to examine the structure of the actual core you want to port. As an easy start, we suggest to go to the core's GitHub repository and browse the source code there. You might want to use the MiSTer Wiki as a starting point to find the repository of the core: Scroll down a bit and you will see the list of cores on the right side.
MiSTer is a very structured project, so we can rely on certain files and folders to be always present:
-
rtl
folder: Contains the actual core. Many MiSTer cores are enhanced versions of MiST cores or other cores. Therefore the MiSTer team encapsulates everything related to the core itself inside thertl
folder. -
sys
folder: This is the MiSTer framework that provides similar services than the MiSTer2MEGA65 framework. -
*.sv
file in the root folder that is named like the core: This is your starting point for any porting effort, because you will be able to study the "wiring" of the MiSTer core: How does MiSTer actually connect different parts of the core with its own framework? Which kind of glue logic is necessary? What options does MiSTer offer to the users? ROMs? Drives? (Hint: The*.sv
file is actually not the top-file used to synthesize a MiSTer core. Instead,sys/sys_top.v
is used. But this does not matter for our porting purposes.)
The MiSTer framework is similar to our M2M framework in being a hardware abstraction layer. The core lives in its own bubble while not being aware of the fact, that it is not connected to the "real" hardware that it expects.
What we need to find out as a next step is: What is the environment that the core needs to run? Examples of "environment" are:
- Clock speed
- RAM
- ROM
- Keyboard
- Other peripherals (drives, joysticks, mouses, paddles, ...)
Additionally, you need to learn how the video and audio output of the core works and what settings / switches / parameters can and need to be configured.
To learn everything about the environment, open the *.sv
file in the root
folder of the core and start looking for the instantiation of the "actual"
core. The *.sv
file usually contains a ton of glue logic and instantiations
of all the hardware needed to support the core. Additionally it contains stuff
that is needed for the MiSTer framework. We need to ignore all of this for now
and instead locate the right module, the "Actual core".
Here are some examples:
Example core | Root *.sv file |
Actual core module |
---|---|---|
Apple II | Apple-II.sv | apple2_top |
Arkanoid | Arcade-Arkanoid.sv | Arkanoid |
Commodore 64 | c64.sv | fpga64_sid_iec |
GameBoy | Gameboy.sv | gb |
Please note that it will be this "actual" core (instead of the emu
module
from MiSTer's root *.sv
file) that you will instantiate at a later stage
inside M2M's main.vhd
. We will get into the details in chapter
6. Basic wiring.
Instead of continuing to talk about the *.sv
file, in the following sections
we use emu
module instead.
MiSTer's system clock runs at 50 MHz. M2M's system clock runs at 100 MHz. Therefore both frameworks need to use PLLs or MMCMs to generate the clock or clocks needed by the retro core.
Most MiSTer cores instantiate a clocking module called pll
within the emu
module. Start by having a look at this instantiation to answer the following
questions:
- How many clocks are being generated?
- What are the names of the clock signals used inside
emu
? - Which clocks are used for the core itself?
- Which clocks are used for video output, RAM, other components?
- Is there a mechanism for any dynamic clock reconfiguration?
There is no recipe for answering these questions other than to read the
source code in the emu
module. It is important that you take a thorough look
at CONF_STR
while doing so because some of the menu items that the end user
can choose from are impacting the clock handling.
Last but not least, you need to learn more about the actual speed of the
clock(s). Please be aware that very often it is crucial for compatibility and
timing that you try to hit the actual clock speed "down to the Hertz" (or
at least very close). In most MiSTer cores, the folder with the file(s) where
you can learn more is called rtl/pll
. Also, in most MiSTer cores the name
of the clock signal generated in the emu
module's pll
section already
gives you a first hint of what is going on.
Here are some examples to make this more tangible:
At Arkanoid, the pll
instantiation looks like this:
pll pll
(
.refclk(CLK_50M),
.rst(0),
.outclk_0(CLK_48M),
.reconfig_to_pll(reconfig_to_pll),
.reconfig_from_pll(reconfig_from_pll),
.locked(locked)
);