\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} Sequence ; < = ? <16_40 + > > 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}