\documentstyle[a4,12pt]{article}
\begin{document}
\author{John Butler}
\title{APM Character handling}
\maketitle
\parskip .1 in
\setcounter{secnumdepth}{10}
\parindent 0in
\section{Preamble}
APM Asynchronous character I/O to and from the local terminal

\section{Input}

The APM operating system reads in characters by interrupt from a Motorola M6850
ACIA at locations 16\_400C1 (control/status) and 16\_400C3 (data). The ACIA
interrupts through auto-vector 5 at location 16\_40074 . The ACIA transmit and
receive speed can be set using a 16-position switch on the processor board front
edge. Allowed speeds are ..

19k2, 9k6, 7k2, 4k8, 3k6, 2k4, 2k0, 1k8, 1k2, 600, 300, 150, 134.5,
110, 75, 50 baud for switch settings 16\_0 - 16\_F respectively.

 The recommended maximum speed is 9k6 baud -
 the Visual 200 Z80 processor may be unable to keep up if this is
exceeded. The ACIA is set up with control = 16\_11 (2 stop bits, 8 bits).
(see [3] for details of Motorola ACIA and 6840 PTM.

Characters are then processed:

1) Non-control characters (ASCII value $>$= 16\_20) are assembled into a
100-byte cyclic keyboard buffer starting at KBBEG. This is indexed by two
absolute pointers:

KBIN points to where the next character will be inserted .
KBEX points to the next character to be removed from the buffer.

The buffer is empty when KBIN = KBEX.

2) Control characters (ASCII values 16\_00 - 16\_1F) are checked against the
bitmap EXEMPT MASK. A 1 indicates an exempted control character
which is to be treated as a normal ASCII character ( 1) above). Exempt mask
defaults to 0.

3) $<$carriage-return$>$ and $<$line-feed$>$ are trapped and exchange values. Typing
$<$return$>$ thus enters $<$linefeed$>$ (=$<$newline$>$).

4) DLE (Ctrl-P) is trapped. It is not stored in the keyboard buffer but the next
character is read and exempted as in 2) above.

5) DC1 (X-On or Ctrl-Q) and DC3 (X-Off or Ctrl-S) are trapped and switch
output on and off respectively.

6) EM (Ctrl-Y) is trapped and causes an event 0, 1.

7) DC4 (Ctrl-T) is trapped and causes the software front panel to be entered.

8) SI (Ctrl-O) is trapped and causes output to the terminal to be discarded until
either SI is entered again or input is next requested.

The kernel will echo BEL (ASCII 7) to any attempt to enter a character when
the keyboard buffer is full and to any non-exempted, non-trapped control character.

Characters may be read from the keyboard buffer by one of two basic
mechanisms:

\subsection{READSYMBOL}

This causes symbols to be read from the keyboard buffer into a line buffer
unless line reconstruction is suppressed (see SET TERMINAL MODE below) in which
case symbols are read directly from the keyboard buffer.
Line reconstruction is performed using the editing characters DEL and CAN (Ctrl-X)
The entire line is made available to the program when a terminating key is typed.

Terminators are $<$carriage-return$>$, $<$linefeed$>$, EM (Ctrl-Y) and the escape
sequences $<$esc$>$ $<$char$>$ or $<$esc$>$ ? $<$char$>$. Escape sequences correspond to
Visual 200 pre-programmed keypad and function key sequences and are never echoed.
Other terminators will generally be echoed but this can be suppressed by
SET TERMINAL MODE bit 1.
All terminators are included in the data read by the program. BS ($<$ASCII 8$>$) and
NAK (Ctrl-U) are mapped onto CAN. SUB (Ctrl-Z) is mapped onto EM.
HT (TAB or Ctrl-I) is mapped into two spaces.
Event 9, 1 is signalled when EM is read from the line buffer.

The line buffer is 96 bytes long, starts at LBEG and is indexed by absolute
pointer LPOS. The buffer has three significant states:

1) LEND = LBEG; LPOS Undefined. - Line buffer is empty.

2) LBEG $<$= LPOS $<$ LEND. - Line buffer contains data with some left
still to read.

3) LBEG $<$ LPOS = LEND. Line buffer is exhausted - all data has been read.

READSYMBOL will suspend the program until a character is read.

\subsection{TESTSYMBOL}

This reads a character from the line buffer if present failing which the
keyboard buffer is examined. If TESTSYMBOL finds a character in either buffer
it will be returned via the result and the appropriate buffer pointer incremented.
A -1 will be returned otherwise so the program never suspends.
No line reconstruction will be performaed on characters read from the keyboard
buffer but the character processing described in 1) - 8) above will be
performed unless disabled using EXEMPT MASK. Note that characters following a
command verb will remain in the line buffer and will be the first characters read
on that stream unless they are first read in using PAM or CLI PARAM.

Derived I/O routines.

a) There are a large number of IMP I/O routines derived from READSYMBOL.
The most important related routine is..

NEXTSYMBOL. Returns the value of the next symbol in the line or keyboard
buffers but doesn't advance the pointer. Suspends until a symbol is read.

b) There are several routines related to TESTSYMBOL.

PENDSYMBOL. Returns the value of the next symbol in the line or keyboard
buffer if present and -1 otherwise. Program is not suspended.

INPUT PENDING. Returns a count of the unread characters in line and
keyboard buffers.

PROBE SYMBOL(character). Returns TRUE if the character is present in line
or keyboard buffers, FALSE otherwise.

CANCEL INPUT. Discards all unread characters from line and keyboard buffers.

\section{Output}

Characters are output as transmitted unless SI has been entered (See input
above). An Event 0 is signalled when ETX (Ctrl-C) is inserted into the line buffer.
By default, 22 lines will be output at which point output will be suspended until
either

a) a DC1 (Ctrl-Q) is entered, in which case output will resume freely

b) the $<$return$>$ key is typed in which case one line is output and output is
suspended again.

c) the $<$linefeed$>$ key is typed in which case 23 further lines are output and
output is suspended again.

The default can be overridden by SET TERMINAL MODE bit 3.

\section{Terminal characteristics}

Normal VDU mode is character echo on, echo terminators, enable line
buffering and halt output after one screenful of data (page mode).
This can be altered using the IMP routine SET TERMINAL MODE. This takes a
bitmap parameter with bits..

\small\tt \begin{verbatim}      0: 0 = normal echo                1 = suppress echo
      1: 0 = normal echo                1 = suppress terminator echo
      2: 0 = normal line buffering      1 = suppress line buffering
      3: 0 = page-mode                  1 = cancel page-mode
\end{verbatim}\rm  \normalsize 
These are all discussed in the text. Default value in all cases is 0.

The ASCII character set is used throughout. All 8 bits are significant -
Text characters are assumed to be generated with the parity bit (2$\hat{ }${}7) = 0.

\section{A note about Visual 200's}

Reference [5] should be consulted for a definitive answer to any questions
concerning the Visual 200 but the following information proved particularily
difficult to extract..

Numeric Keypad

The keypad transmits the characters $<$k$>$ indicated on the keycaps until the
sequence $<$escape$>$ $<$char$>$ is received wherupon it transmits the following sequences
when $<$k$>$ is typed..

\small\tt \begin{verbatim}      <char>      Sequence

      ;           <escape> <k>
      <           <stx> <k> <return>
      =           <escape> ? <16_40 + <k>> 
      >           <k>   i.e. resets the keypad for normal operation.
\end{verbatim}\rm  \normalsize 
The cursor arrows left, right, up, down, home transmit the sequences $<$escape$>$
$<$ch$>$ where $<$ch$>$ is 16\_68, 16\_67, 16\_65, 16\_66, 16\_72 respectively.

\section{Access to character I/O facilities}

Reference [3] contains definitions of KBBEG, KBIN, KBEX, LBEG, LPOS, LEND,
EXEMPT MASK and the source of INPUT PENDING, PROBE SYMBOL, PENDSYMBOL
and CANCEL INPUT.
TESTSYMBOL and SET TERMINAL MODE are IMP permanent procedures.

\section{References}

\small\tt \begin{verbatim}[1]    APM 1.1: APM working notes
[2]    APM 1.5: Motorola M6840 PTM & M6850 ACIA specifications
[3]    APM 2.1: The Imp-77 Language
[4]    APM 3.6: i:chario.inc 
[5]    Visual 200 reference manual
\end{verbatim}\rm  \normalsize 
\vspace{.75in} view:chario printed on 16/02/89 at 16.25

\newpage
\tableofcontents
\end{document}
