appendix-keyboard.tex

\chapter{The MEGA65 Keyboard}
\label{cha:keyboard}

The MEGA65 has a full mechanical keyboard which is compatible with the C65 and
C64 keyboards, and features four distinct cursor keys which work in both C64
and C65-mode, as well as eleven new C65 keys that normally work only in
C65-mode.

There are several ways to read the keyboard from programs. BASIC programs can
use the {\bf GET} or {\bf GETKEY} commands, which read a PETSCII keycode into
a variable, without or with waiting for a typing event. Machine language
programs that keep the KERNAL active can use the KERNAL {\tt getin} routine at
\$FFE4, which loads a PETSCII code into the accumulator. These routines have
the advantage of supporting other features of the KERNAL input stream, such as
function key macros and input redirection.

The Commodore 64 uses the CIA chip as the hardware interface to the keyboard,
and some C64 programs (including the C64 KERNAL) read the keyboard matrix
directly off of the CIA lines. This is implemented in the MEGA65 chipset to
support these programs. Reading the keyboard from the CIA has the potential to
miss key presses, requires translating CIA signals to keyboard characters in
software, and requires managing typing features such as key repeat in software
as well.

For greater accuracy and ease of coding in common typing-style keyboard
applications, the MEGA65 provides a {\em typing event queue} implemented
directly in hardware. A {\em typing event} occurs when the user presses a
non-modifier key, holding zero or more modifier keys down while doing so. The
typing event queue remembers the key being pressed and the modifiers being
held, for up to a certain number of events. The program is expected to dequeue
each event as it is processed, making room in hardware memory for new events.
A program can read typing events as either PETSCII or ASCII values directly
from hardware registers. The modifier keys associated with the event are also
readable from a register.

The MEGA65 KERNAL uses the typing event queue to power {\tt getin} and the
BASIC {\bf GET} and {\bf GETKEY} commands. Reading a key using any of these
methods dequeues a typing event from the queue.

\section{Using the Typing Event Queue}

The status of the typing event queue is visible on these registers:

\begin{center}
\begin{tabular}{|p{5.5em}|p{6em}|p{22em}|}
\hline
\bf{Name} & \bf{I/O address} & \bf{Description} \\
\hline
ASCIIKEY & \$D610 & The top event as ASCII, \$FF if no interpretation, or \$00 if queue is empty \\
\hline
PETSCIIKEY & \$D619 & The top event as PETSCII, or \$FF if no interpretation \\
\hline
MODKEY & \$D60A[0:6] & Modifier keys held during the event \\
\hline
KEYQUEUE & \$D60A[7] & 1 if the queue is non-empty \\
\hline
\end{tabular}
\end{center}

The bits of MODKEY correspond to these modifier keys, with 1 meaning the key
was held during the event:

\begin{center}
{\renewcommand{\arraystretch}{1.7}
\begin{tabular}{|*{7}{>{\centering\arraybackslash}p{3em}|}}
\hline
\bf{Bit 6} & \bf{Bit 5} & \bf{Bit 4} & \bf{Bit 3} & \bf{Bit 2} & \bf{Bit 1} & \bf{Bit 0} \\
\hline
\specialkey{CAPS\\LOCK} & \specialkey{NO\\SCROLL} & \specialkey{ALT} & \megasymbolkey & \specialkey{CTRL} & \specialkey{SHIFT\\right} & \specialkey{SHIFT\\left} \\
\hline
\end{tabular}}
\end{center}

If ASCIIKEY (\$D610) reads as \$00, then the typing queue is empty. A program
must test ASCIIKEY for \$00, or test KEYQUEUE (bit 7 of \$D60A), to determine
if the queue is empty. The PETSCIIKEY register does not have a value that
represents the empty queue.

A given typing event may or may not have an ASCII or PETSCII interpretation. A
typing event that has neither is not added to the queue. If an event has an
ASCII interpretation but not a PETSCII interpretation, then ASCIIKEY will
contain the ASCII value, and PETSCIIKEY will contain \$FF. Similarly, ASCIIKEY
will contain \$FF for typing events without an ASCII interpretation. The
program is expected to use the other registers to determine whether the queue
is empty, and skip typing events that do not have an interpretation useful to
the program.

\underline{NOTE}: ASCII also uses \$FF to represent the "umlaut-y" character
(Alt+Y). In this case (and only in this case), PETSCIIKEY is \$59 (regular Y).
If your program needs to distinguish between a non-ASCII typing event and
Alt+Y, test whether PETSCIIKEY is \$59 when ASCIIKEY is \$FF.

To dequeue the top typing event, write any value to either ASCIIKEY (\$D610)
or PETSCIIKEY (\$D619). If the queue has another event, it becomes visible on
the registers. Otherwise, the registers go to their empty queue state.

\subsection{Reading Immediate Modifier Keys}

In addition to recording the modifier keys pressed during a typing event, a
program can read the immediate state of the modifier keys with register
\$D611. This uses the same bit pattern as MODKEY. See the table, above.

Remember that the immediate modifier key register represents the current state
of the modifier keys being held, which may be different from the modifier keys
held during the typing event at the top of the queue.

\subsection{Interpreting ASCII Typing Events}

The ASCIIKEY register makes it possible to read entry of the ASCII symbols not
available in PETSCII, including \{, \_ and |, which are not possible to type
on a normal C64 and C128 keyboards. The keyboard and the ASCII interpretation
supports most Latin-1 code-page characters, allowing the entry of many
accented characters. These keys are entered by holding down \megasymbolkey and
pressing other keys or key-combinations. The use of ASCII or Unicode
basic-Latin symbols not present in the PETSCII character set requires the use
of a font that contains these symbols, and software which supports them.

The following tables show the hex value and Unicode character that will be
produced by each key combination on the ASCIIKEY register. One table is
provided for pressing a key on its own, and one table for each of the
\specialkey{SHIFT}, \specialkey{CTRL}, \megasymbolkey, and \specialkey{ALT}
keys.

\begin{minipage}{\textwidth}
\bf{Keys pressed alone:}
\input{keymap_table_1}
\end{minipage}

\begin{minipage}{\textwidth}
\bf{Keys pressed with \specialkey{SHIFT}}
\input{keymap_table_2}
\end{minipage}

\begin{minipage}{\textwidth}
\bf{Keys pressed with \specialkey{CTRL}}
\input{keymap_table_3}
\end{minipage}

\begin{minipage}{\textwidth}
\bf{Keys pressed with \megasymbolkey}
\input{keymap_table_4}
\end{minipage}

\begin{minipage}{\textwidth}
\bf{Keys pressed with \specialkey{ALT}}
\input{keymap_table_5}
\end{minipage}

\subsection{Unicode Basic-Latin Keyboard Map}

The following tables are a convenient reference to help you find a key combination
that will produce the desired ASCII/Unicode basic-Latin character code.  Note that
a very few codes are difficult to type in practice, because they are mapped to
key combinations that perform other functions. In particular, the combination of
\megasymbol + \specialkey{TAB} is normally overridden by the Matrix Mode hardware
debug feature.

\input{unicode_mapping}


\section{Keyboard Theory of Operation}

The MEGA65 keyboard is a full mechanical keyboard, constructed as a matrix. Every
key switch is fitted with a diode, which allows the keyboard hardware to detect
when any combination of keys are pressed at the same time.  This matrix is scanned
by the firmware in the CPLD chip on the keyboard PCB many thousands of times per
second.  The matrix arrangement of the MEGA65 keyboard does not use the C65
matrix layout.

Instead, the CPLD also sorts the natural matrix of the keyboard
into the C65 keyboard matrix order, and transmits this serially via the keyboard
cable to the MEGA65 mainboard.  The MEGA65 core reads this serial data and uses it
to reconstruct a C65-compatible virtual keyboard in the FPGA.  This virtual keyboard
also takes input from the on-screen-keyboard, synthetic keyboard injection mechanism
and/or other keyboard input sources depending on the MEGA65 model.

The end-to-end latency of the keyboard is less than one milli-second.

\section{C65 Keyboard Matrix}

The MEGA65 keyboard presents to legacy software as a C65-compatible keyboard.
In this mode all keys are available for standard PETSCII scanning as per normal.
There is also a hardware accelerated mechanism for detecting arbitrary combinations
of keys that are held down. This is via \$D614 (decimal 54804).  Writing a value
between 0 and 8 to this register selects the corresponding row of the C65 keyboard
matrix, which can then be read back from \$D613.
If a bit is zero, then it means that the key is being pressed. If the bit is one, then
the key is not being pressed.

The left and up cursor keys are special, because they logically press cursor right or down, and the right shift key.
To be able to differentiate between these two situations, you can read \$D60F: Bit 0 is the state of the left cursor
key and bit 1 is the state of the up cursor key.

The C65 keyboard matrix layout is as follows:

\index{Keyboard!matrix}
{\ttfamily
{
\setlength{\def\arraystretch{1.5}\tabcolsep}{1mm}
\begin{center}
\begin{tabular}{|c*{9}{|C{1.02cm}}|}
\hline
& \bf{0} & \bf{1} & \bf{2} & \bf{3} & \bf{4} & \bf{5} & \bf{6} & \bf{7} & \bf{8} \\
\hline
\small  \bf{0} & \specialkey{INST\\DEL} & 3 & 5 & 7 & 9 & + & \pounds & 1 & \specialkey{NO\\SCROLL} \\
\hline
\small  \bf{1} & \specialkey{RETURN} & W & R & Y & I & P  & * & \megakeywhite{$\leftarrow$} & \specialkey{TAB} \\
\hline
\small  \bf{2} & \megakey{$\rightarrow$} & A & D & G & J & L & ; & \specialkey{CTRL} & \specialkey{ALT}  \\
\hline
\small  \bf{3} & \megakey{F7} & 4 & 6 & 8 & 0 & - & \specialkey{CLR\\HOME} & 2 & \specialkey{HELP} \\
\hline
\small  \bf{4} & \megakey{F1} & Z & C & B & M & . & \specialkey{SHIFT\\right} & \megakey{SPC} & \megakey{F9} \\
\hline
\small  \bf{5} & \megakey{F3} & S & F & H & K & : & = & \megasymbolkey & \megakey{F11} \\
\hline
\small  \bf{6} & \megakey{F5} & E & T & U & O & @ & \megakeywhite{$\uparrow$} & Q & \megakey{F13} \\
\hline
\small  \bf{7} & \megakey{$\downarrow$} & \specialkey{SHIFT\\left} & X & V & N & , & / & \specialkey{RUN\\STOP} & \specialkey{ESC} \\
\hline
\end{tabular}
\end{center}
}}

Note that the keyboard matrix is identical to the C64 keyboard matrix, except for the addition of one extra column
on the right-hand side.  While columns 0 to 7 can be controlled via CIA1 just like on the C64, column 8 is controlled
via I/O port E with its data register at \$D607 and data direction register at \$D608.  Bit 1 of this port controls 
the extra column 8.  The cursor left and up keys on the MEGA65 and C65 are implemented as cursor right and down, but
with the right shift key applied.  This enables them to work in C64-mode.  \specialkey{CAPS\\LOCK} is not
part of the matrix, but has its own dedicated line.  Its status can be read from bit 6 of register \$D611 (decimal 54801):

The numbers across the top indicate the columns of the matrix, and the numbers down the left indicate the rows.
The unique scan code of a key is calculated by multiplying the column by eight, and adding the row.  For example,
\specialkey{CLR\\HOME} is in column 6 and row 3. Thus its scan code is $6 \times 8 + 3 = 51$.

\section{Synthetic Key Events}

The MEGA65 keyboard interface logic allows the use of a variety of keyboard types and alternatives. This is partly
to cater for the early development on general purpose FPGA boards, the MEGAphone with its touch interface, and the
desktop versions of the MEGA65 architecture.  The depressing of up to 3 three keys can be simulated via
the registers \$D615 -- \$D617 (decimal 54,805 -- 54,807).  By setting the
lower 7 bits of these registers to any C65 keyboard scan code, the MEGA65 will behave as though that key is being
held down. \widekey{RESTORE} exists outside of the keyboard matrix, as on the C64.  To simulate
holding \widekey{RESTORE} down, write \$52 (ASCII code for a capital R), and to simulate a quick tap
of the \widekey{RESTORE}, write \$72 (ASCII code for a lowercase R).  Another value must be written after the
\$72 value has been written, if you wish to simulate multiple presses of \widekey{RESTORE}.

To release a key, write \$7F (decimal 127) to the register containing the active key press. For example,
to simulate briefly pressing the * key, the following could be used:

\begin{tcolorbox}[colback=black,coltext=white]
\verbatimfont{\codefont}
\begin{verbatim}
POKE DEC("D615"),6*8+1:FORI=1TO100:NEXT:POKE DEC("D615"),127
\end{verbatim}
\end{tcolorbox}

The FOR loop provides a suitable delay to simulate holding the key for a short time.  All statements should be on a single line
like this, if entered directly into the BASIC interpreter, because otherwise the MEGA65 will continue to act as though the * key
is being held down, making it rather difficult to enter the other commands!

\section{Keyboard LED Control}

The LEDs on the MEGA65's keyboard are normally controlled automatically by the
system.  However, it is also possible to place them under user control.  This
is activated by setting bit 7 (decimal 128) of \$D61D (decimal 54813).  The
lower bits indicate which keyboard LED to set.  Values 0 through 11 correspond
to the red, green and blue channels of the four LEDs. The table below shows the
specific values:

\begin{adjustwidth}{}{-2cm}
\begin{description}[align=left,labelwidth=0.2cm]
\item[ 0] left-half of DRIVE LED, RED
\item[ 1] left-half of DRIVE LED, GREEN
\item[ 2] left-half of DRIVE LED, BLUE
\item[ 3] right-half of DRIVE LED, RED
\item[ 4] right-half of DRIVE LED, GREEN
\item[ 5] right-half of DRIVE LED, BLUE
\item[ 6] left-half of POWER LED, RED
\item[ 7] left-half of POWER LED, GREEN
\item[ 8] left-half of POWER LED, BLUE
\item[ 9] right-half of POWER LED, RED
\item[10] right-half of POWER LED, GREEN
\item[11] right-half of POWER LED, BLUE
\end{description}
\end{adjustwidth}

Register \$D61E (decimal 54814) is used to specify the intensity that should be
given to a specific LED (value between 0 and 255).

Note that whatever value is in \$D61E gets written to whatever register is
currently selected in \$D61D.  Therefore to safely change the intensity of one
specific LED ensure \$D61D is set to 255 first. This prevents affecting another
LED when we set the intended intensity value into \$D61E. Now select the target
LED by setting \$D61D to 128 + x, where x is a value from the table above.
Hold the \$D61D, \$D61E configuration for approximately one millisecond to give
the keyboard logic enough time to pick up the new intensity value for the
selected LED.

To return the keyboard LEDs to hardware control, clear bit 7 of \$D61D.

For example to pulse the keyboard LEDs red and blue, the following program
could be used:

\begin{tcolorbox}[colback=black,coltext=white]
\input{examples/ledcycle}
\end{tcolorbox}

\section{Native Keyboard Matrix}

The native keyboard matrix is accessible only from the CPLD on the MEGA65's keyboard.
If you are programming the MEGA65 computer, you should not need to use this.

\begin{adjustwidth}{}{-2cm}
\begin{multicols}{2}
\begin{description}[align=left,labelwidth=0.2cm]
    \item [0] \megakey{F5}
    \item [1] 9
    \item [2] I
    \item [3] K
    \item [4] <
    \item [5] \specialkey{INST\\DEL}
    \item [6] \specialkey{CLR\\HOME}
    \item [7] O
    \item [8] \megakey{F3}
    \item [9] 8
    \item [10] U
    \item [11] J
    \item [12] M
    \item [13] \megakey{$\rightarrow$}
    \item [14] \pounds
    \item [15] =
    \item [16] \megakey{F1}
    \item [17] 7
    \item [18] Y
    \item [19] H
    \item [20] N
    \item [21] \megakey{$\downarrow$}
    \item [22] -
    \item [23] ;
    \item [24] Reserved
    \item [25] 6
    \item [26] T
    \item [27] G
    \item [28] B
    \item [29] \megakey{$\leftarrow$} (cursor left)
    \item [30] +
    \item [31] :
    \item [32] \specialkey{NO\\SCROLL}
    \item [33] 5
    \item [34] R
    \item [35] F
    \item [36] V
    \item [37] \megakey{SPACE}
    \item [38] 0
    \item [39] L
    \item [40] \specialkey{CAPS\\LOCK}
    \item [41] 4
    \item [42] E
    \item [43] D
    \item [44] C
    \item [45] Reserved
    \item [46] \specialkey{HELP}
    \item [47] \specialkey{RETURN}
    \item [48] \specialkey{ALT}
    \item [49] 3
    \item [50] W
    \item [51] S
    \item [52] X
    \item [53] \megakey{$\uparrow$} (cursor up)
    \item [54] \megakey{F13}
    \item [55] \megakeywhite{$\uparrow$} (next to \widekey{RESTORE})
    \item [56] \specialkey{ESC}
    \item [57] 2
    \item [58] Q
    \item [59] A
    \item [60] Z
    \item [61] right \specialkey{SHIFT}
    \item [62] \megakey{F11}
    \item [63] *
    \item [64] Reserved
    \item [65] 1
    \item [66] Reserved
    \item [67] Reserved
    \item [68] left \specialkey{SHIFT} and \specialkey{SHIFT\\LOCK}
    \item [69] /
    \item [70] \megakey{F9}
    \item [71] @
    \item [72] \specialkey{RUN\\STOP}
    \item [73] \megakeywhite{$\leftarrow$} (next to 1)
    \item [74] \specialkey{TAB}
    \item [75] \specialkey{CTRL}
    \item [76] \megasymbolkey
    \item [77] >
    \item [78] \megakey{F7}
    \item [79] P
\end{description}
\end{multicols}
\end{adjustwidth}