mega65-developer-guide.tex

\input{common-header}
\input{frontcover}
\input{regulatory}
\input{updates}

% paper title
% Titles are generally capitalised except for words such as a, an, and, as,
% at, but, by, for, in, nor, of, on, or, the, to and up, which are usually
% not capitalised unless they are the first or last word of the title.
% Linebreaks \\ can be used within to get better formatting as desired.
% Do not put math or special symbols in the title.

\cleardoublepage

\pagenumbering{roman}

  \begin{titlepage}
    \pagecolor{blue}
     \begin{center}
       {
         \large
         % Put a nice amount of vertical space before the title
         \vspace*{2cm}
               {\Huge\textcolor{white}{\bf{Developing for the MEGA65}}}\\
             \vspace{\fill}
                    {\textcolor{white}
                    {Published by \\ the MEGA Museum of Electronic Games \& Art e.V., Germany.}}
       }
     \end{center}
   \end{titlepage}

% Then the copyright notice page
  \pagecolor{white}\textcolor{black}
  \vfill
  WORK IN PROGRESS

  \index{copyright}Copyright \copyright 2019 -- 2021 by Paul Gardner-Stephen,
  the MEGA Museum of Electronic Games \& Art e.V.,
  and contributors.

  This reference guide is made available under the GNU Free Documentation
  License v1.3, or later, if desired. This means that you are free to
  modify, reproduce and redistribute this reference guide, subject to
  certain conditions. The full text of the GNU Free Documentation
  License v1.3 can be found at
  \url{https://www.gnu.org/licenses/fdl-1.3.en.html}.

  Implicit in this copyright license, is the permission to duplicate
  and/or redistribute this document in whole or in part for use in
  education environments. We want to support the education of future
  generations, so if you have any worries or concerns, please contact us.

   \par\today

\newpagestyle{onlynumber}{\setfoot[][{\bf\small\thepage}][]
                                  {} {\bf\small\thepage} {}}
\pagestyle{onlynumber}
\pagecolor{white}

\tableofcontents

%% XXX - big numbers are not in bold, because latex gets confused
\newcommand*{\justifyheading}{\raggedleft}
\definecolor{headingblue}{rgb}{0.5,0.5,1}

% \titleformat{command}[shape]
%   {format}
%   {label}
%   {sep}
%   {before}
%   [after]

% ***************
% PART title page
% ***************

\titleclass{\part}{top}
\titleformat{\part}[display]
   {\thispagestyle{empty}\pagecolor{blue}\normalfont\huge\bfseries\justifyheading}
   {\textcolor{white}{\fontsize{50}{65}\selectfont\bf{PART}\quad{\fontsize{100}{130}\selectfont \bf{\serifed\thepart}}}}
   {20pt}
   {\Huge\textcolor{white}}
   [\newpage\pagecolor{white}\textcolor{black}]

% ******************
% CHAPTER title page
% ******************

\titleformat{\chapter}[display]
   {\thispagestyle{empty}\pagecolor{blue}\normalfont\huge\bfseries\justifyheading}
   {\textcolor{white}{\MakeUppercase{\chaptertitlename}\quad{\fontsize{100}{130}\selectfont \bf\thechapter}}}
   {20pt}
   {\Huge\textcolor{white}}
   [{\chapmtoc\insertminitoc}\newpage\pagecolor{white}\textcolor{black}\cleardoublepage]

% ******************
% SECTION title page
% ******************

\titleformat{\section}[display]
   {\raggedright}
   {\thesection}
   {20pt}
   {\huge\bf\color{headingblue}\uppercase}
   [\color{black}]

\input{introduction}

\cleardoublepage
\pagenumbering{arabic}

\part{INTRODUCTION}

\chapter{Welcome, and thank you!}

I would like to begin by thanking you for your interest in the MEGA65,
and in developing software to run on it. The success of the MEGA65 as
a fun retro-computing platform depends on there being enough
interesting software for people to run on it.  This requires the
generous work of developers like yourself. So, again, thank you!

But developing for the MEGA65 is not merely a case of giving to the
benefit of others. We have tried hard to create a machine that is as
fun to program as the Commodore 64, but with some of the barriers
and frustrations worn down somewhat.  That is, it is our intention
that people develop on the MEGA65 because it is fun, and then enjoy
the process.  That is, the journey should very much be the
destination.

Now, in saying that, the MEGA65 is quite new, and we have been flat
out creating the machine. This means that some development tools are
not as ready or as simple or integrated as we would like.  Improving
the tools is also an area where we hope that many of you will enjoy
contributing, so that developing for the MEGA65 can become accessible
to as many people as possible.

If you encounter barriers to your
journey of developing for the MEGA65, please do let us know, and
consider creating solutions that can be shared with others.  This will
help everyone to enjoy being an active part of the MEGA65 ecosystem.

Finally, my apologies to anyone who has developed tools or utilities
for the MEGA65 that have escaped my memory as I have written this
document.  If this is the case, please drop me an email, and I'll
update this document to include them.

\chapter{Other Resources}

This book focusses on the process of developing for the MEGA65.  To
avoid it being a thousand pages long, it doesn't describe the inner
workings of the MEGA65, except where you need to know about them, so
that you can engage in the development process.  For example, if you
wish to know about the capabilities of the various custom chips in the
MEGA65, and which registers do which things, please refer to {\em the
MEGA65 Book} online
at \url{https://github.com/mega65/mega65-user-guide}, or consider
purchasing one or more of the reference volumes for the MEGA65, from
which the MEGA65 Book is formed.  For example, the {\em MEGA65 Chipset
Reference Guide} or the {\em MEGA65 Assembly Language Reference Guide}.

We also hope that you, the developer community, will contribute to
those books, or write your own material that can help others in their
journies with developing for the MEGA65.

\part{CROSS-PLATFORM DEVELOPMENT TOOLS}

\input{emulators}
\input{transferanddebugging}
\input{assemblers}
\input{ccompilers}
\input{libc}
\input{basictokenisers}

\part{NATIVE DEVELOPMENT TOOLS}

\chapter{C65 Memory Monitor}

\chapter{MEGA65 Matrix Mode}

\chapter{Turbo Assembler}

\chapter{Dealing with C65 and C64-mode}

The MEGA65 normally starts in C65-mode, and there is appeal in making
programs that can start directly from C65-mode.  However, the
different versions of the C65 ROM make this difficult, as there are
differences in the memory location of various system variables and ROM
routines.  If you are developing a program in assembly language or
C, it is typically easier to develop it for C64-mode.

But that leaves
you with the problem of how to allow it to be started from C65-mode.
Our solution to this is the \stw{c65toc65wrapper.asm} program.  This
short program can be found in the \stw{src/utilities} directory of
the \url{https://github.com/mega65/mega65-tools} repository.  When
compiled, it produces a short program that you can pre-pend to your
C64-mode oriented MEGA65 program, and have it automatically detect
C64 or C65-mode, switch to C64-mode if required, and set your
program going. It also switches the CPU to 40MHz.  The only
assumption it makes, is that your program should be started using
\stw{SYS 2061}

This program is particularly handy when using exomizer, as by having
the CPU set to 40MHz before depacking allows depacking to happen
almost instantly.  This is important on the MEGA65, as loading a
program often takes only a fraction of a second, but depacking an
exomized program at 1MHz can take several seconds.

Finally, you can use this approach to create bootable disks for the
MEGA65, by placing the file onto the disk with the
name \stw{AUTOBOOT.C65}.  This allows you to use C64-mode programs
to autoboot on the MEGA65, which is itself very convenient.

\part{MEGA65 Operating System}

\input{developing-system-programs}

{\input{appendix-hypervisor-calls}}

\part{MULTI-MEDIA AND DATA CONVERSION}

\part{GEOS Development}

\part{HARDWARE}

\input{nexys4ddr-setup}

\part{APPENDICES}

\begin{appendices}

  \input{appendix-mega65r2-flashing}
  \input{appendix-troubleshooting}
  \input{appendix-schematics}
  \input{appendix-donors}
\end{appendices}


\nocite{*}
\bibliographystyle{IEEEtran}
\bibliography{references}

\printindex

\input{common-footer}