-
Notifications
You must be signed in to change notification settings - Fork 50
/
developing-system-programs.tex
116 lines (80 loc) · 8.93 KB
/
developing-system-programs.tex
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
\chapter{Developing System Programmes}
\section{Introduction}
The MEGA65 has a number of system programs and utilities that are used at various times to perform various functions.
This includes the utilities accessible via the Utility Menu \index{Utility Menu}, the Freeze Menu \index{Freeze Menu} and
its own helper programs, as well as the Flash Menu \index{Flash Menu}\index{MEGA Flash}.
A number of these system programs are pre-loaded into the MEGA65 bitstream, while others live on the SD card.
For those that are pre-loaded into the MEGA65 bitstream, this works by having areas of pre-initialised memory, that
contain the appropriate program. For example, the utilities accessible via the Utility Menu are all located in
the colour RAM, while the Flash Menu is located at \$50000 -- \$57FFF.
In one sense, the easiest way to test new versions of these utilities is to generate a new bitstream with the updated versions.
However, synthesising a new bitstream is very time consuming, typically taking an hour on a reasonably fast computer.
Therefore this chapter explains the procedure for loading an alternate version of each of these system programs, as well as
providing some useful information about these programs, how they operate, and the environment in which they operate compared
with normal C64 or C65-mode programs.
\section{Flash Menu}
The flash menu is located in pre-initialised RAM at \$50000 -- \$57FFF. It is executed during the first boot each time the
MEGA65 is switched on. It is unusual in that it executes in the hypervisor context. This is so that it has access to
the QSPI
flash, which is not available outside of Hypervisor Mode, so that user programs cannot corrupt the cores stored in the flash.
It is also important to note that the flash menu program must fit {\em entirely} below \$8000 when loaded {\em and} executing, as the Hypervisor is still mapped at \$8000 -- \$BFFF, and can easily be corrupted by an ill behaved flash menu program. In this regard, the flash menu
can be regarded as an extension of the hypervisor that is discarded after the first boot.
This is unlike all other system programs, that operate in a dedicated memory context, from where the Hypervisor is safe from corruption. It also means that you can't crunch the flash menu to make it fit, as it would overwrite the Hypervisor during decrunching.
Also, as the flash menu is executed very early in the boot process, only the pre-included OpenROM ROM image is available. Thus you must ensure that your flash menu program is compatible with that ROM.
The Hypervisor maintains a flag that indicates whether the flash menu has been executed or not. This flag is updated at the point
where the Hypervisor exits to user mode for the first time, since after that point, the contents of \$50000 -- \$57FFF can no longer
be trusted to contain the flash menu. This means that if you wish to have the Hypervisor run a new version of the flash menu that
you have loaded, you must prevent the Hypervisor from exiting to user mode first.
The easiest way to achieve this is to hold the ALT key down while powering on the MEGA65. This will cause the Hypervisor to display the Utility Menu, rather than exiting to user mode. It is safe at this time to use the {\tt m65} utility to load the replacement flash menu program using a command similar to the following:
\begin{tcolorbox}[colback=black,coltext=white]
\verbatimfont{\codefont}
\begin{verbatim}
m65 -@ newflashmenu.prg@50000
\end{verbatim}
\end{tcolorbox}
That command would load the file {\tt newflashmenu.prg} at memory location \$50000.
After that, you can simply press the reset button on the side of the MEGA65 while holding \specialkey{NO\\SCROLL} down,
and it will boot again, and because it never left Hypervisor Mode during the previous boot cycle, it will run your
updated flash menu program.
It should also be possible to completely automate this process, by first using {\tt m65 -b} to load a new bitstream, thus simulating a cold boot, and then quickly calling {\tt m65} again to simulate depressing the ALT key (or herhaps simply halting the processor), then {\tt m65 -@ ...} and finally {\tt m65 -F} to reset the machine. Writing a script or utility that correctly implements this automation is left as an exercise for the reader.
\section{Format/FDISK Utility}
The Format/FDISK utility is accessed as part of the Utility Menu system. These utilities are compiled, crunched and linked using the
{\tt utilpacker} program. If you have checked out the mega65-core source repository, you can re-build the colour RAM image by using:
\begin{tcolorbox}[colback=black,coltext=white]
\verbatimfont{\codefont}
\begin{verbatim}
make bin/COLOURRAM.BIN
\end{verbatim}
\end{tcolorbox}
You will of course need to first have modified the Format/FDISK utility, which is normally located in the {\tt src/mega65-freeze-menu} subdirectory.
You need to then load this modified colour RAM image into the running machine. Similar to when updating the flash menu, the Hypervisor will
only present the utility menu on the first boot, before exiting to user mode for the first time, because it cannot otherwise be sure that
the colour RAM contains the valid utility programs.
So as for the flash menu, you would power the MEGA65 off, and then holding the ALT key down, you switch the MEGA65 back on, so that it displays the utility menu. At this point you can use the following command to load your modified {\tt COLOURRAM.BIN} file:
\begin{tcolorbox}[colback=black,coltext=white]
\verbatimfont{\codefont}
\begin{verbatim}
m65 -c COLOURRAM.BIN
\end{verbatim}
\end{tcolorbox}
You can now hold \specialkey{ALT} down, and press the reset button on the left-hand side of the MEGA65, which should
again present
the utility menu,
but this time with your modified format/fdisk utility in place.
\section{Keyboard Test Utility}
The process for updating the Keyboard test utility is essentially the same as for the format/FDISK utility, as it lives in the colour RAM
\section{MEGA65 Configuration Utility}
The process for updating the MEGA65 Configuration utility is essentially the same as for the format/FDISK utility, as it lives in the colour RAM
\section{Freeze Menu}
The Freeze Menu is a normal program, which is stored in {\tt FREEZER.M65} on the SD card's FAT32 file system.
To updated the Freeze Menu, simply use the {\tt m65ftp} utility or some other means to upload your updated FREEZER.M65 file to the SD card's FAT32 file system. The format of the program is simply a C64-mode PRG file, just renamed to FREEZER.M65.
\section{Freeze Menu Helper Programmes}
The Freeze Menu helper programs are updated in the same way as the Freeze Menu itself.
\section{Hypervisor}
The Hypervisor is normally built as HICKUP.M65, a 16KB file that contains the complete Hypervisor program. MEGA65 bitstreams contain a pre-build version located at \$FFF8000 -- \$FFFBFFF. Updated versions of the Hypervisor can be tested using two main approaches:
\begin{itemize}
\item 1. Place the updated HICKUP.M65 file on the FAT32 file system of the SD card, and then power the MEGA65 off and on. This works because the Hypervisor contains code that checks for an updated version of itself, and if found, loads it. However this approach is problematic in that if you install a newer bitstream, it will still downgrade the Hypervisor to whatever version is found in the HICKUP.M65 file on the SD card. This method is only recommended for developers who have a need to test their modified Hypervisor code from a cold start. Even then, it is recommended to remove the HICKUP.M65 file immediately after testing to avoid unexpected down-grading in the future.
\item 2. Use the m65 command's {\tt -k} option to replace the Hypervisor in place, and then reset the MEGA65 using the reset button on the left-hand side of the case. This should be done when the Hypervisor is {\em not} active, so that corruption of current execution cannot occur. However, it must also occur before any ROM has been loaded to replace the default OpenROM image. This is because the Hypervisor will attempt to call into the ROM on first-boot in prepration for calling the flash menu, and assumes that the OpenROM is present, because it uses a special OpenROM-specific call to initialise parts of the system state for the flash menu. This is best done by using a command like {\tt m65 -k bin/HICKUP.M65 -R bin/MEGA65.ROM} to load both a new Hypervisor program and re-load an OpenROM image.
\end{itemize}
\section{OpenROM}
To load a new version of a ROM, there are several options, including replacing both the Hypervisor and ROM at the same time, as described above. However, typically the easiest is to copy the new ROM onto the FAT32 filesystem of the SD card as either MEGA65.ROM, or MEGA65$x$.ROM, where $x$ is replaced by a digit between 0 and 9. When resetting the MEGA65, MEGA65.ROM will then be loaded as normal, or if a digit between 0 and 9 is held down on the keyboard while resetting, the Hypervisor will instead load MEGA65$x$.ROM, where $x$ is the number being held down on the keyboard.