home *** CD-ROM | disk | FTP | other *** search
/ Columbia Kermit / kermit.zip / archives / researchmachines.zip / rmlifadoc.txt < prev    next >
Text File  |  1985-07-11  |  16KB  |  420 lines
  1. File  RMKIFACE.DOC
  2. ------------------        Chris Kennington    8th July 1985.
  3.  
  4.  
  5.  
  6.         Research Machines Kermit Software Interfaces
  7.         --------------------------------------------
  8.  
  9.  
  10. 0.  Structure of RM Kermit.
  11.     -----------------------
  12.  
  13.      The bulk of RM Kermit is written in standard C, designed to be
  14. portable between micros and micro operating systems.  The actual
  15. implementations carried out at RML are for the RML 480Z, a Z80-based
  16. micro running under CP/M, and for the RM Nimbus, a 80186-based micro
  17. running (in this instance) under MSDOS.  Since the performace and
  18. acceptability of Kermit depends heavily on its handling of keyboard,
  19. screen and communications line, no attempt was made to use standard
  20. CP/M or MSDOS functions for these purposes.  Instead, a software
  21. interface to these routines was specified and hardware-dependent
  22. low-level routines coded to connect this interface to the necessary
  23. functions.  (Due to the various possible hardware configurations,
  24. there are in fact several different sets of such routines.)
  25.  
  26.      There are also a small number of organizational procedures
  27. which may differ according to the micro OS used and other 
  28. characteristics of the environment.
  29.  
  30.      Since a set of routines specific to the implementation have
  31. to be created and included, opportunity was taken to make some of
  32. the texts displayed also variable, so that help and other information
  33. is more closely appropriate to the version being run.
  34.  
  35.      This document describes these interfaces and lists the texts.
  36. For further information about specific cases, see file RMKGEN.DOC.
  37.  
  38.  
  39.  
  40. 1.  Keyboard/Screen Interface.
  41.     --------------------------
  42.  
  43.  
  44. 1.1  Screen-Handling.
  45.  
  46.      Kermit mostly divides the screen into a 4-line parameter area
  47. at the top, a fixed divider line, and a 19/20-line scrolling area
  48. occupying the rest of the screen.  When in one of the menu modes,
  49. a further 5-line section plus divider is fixed at the bottom, leaving
  50. 14 or 15 lines for the menu.
  51.  
  52.      Some optimisation of output has been done, to provide the fastest
  53. display of information compatible with reasonable flexibility.  Calls to
  54. printf() are used where it is necessary to format binary numbers
  55. and variable strings into other text, but other procedures are used to display
  56. fixed strings and individual characters at the current cursor position.
  57. All map into calls to the special screen-output procedure outc(), via a
  58. formatting routine outfc() which expands tabs etc. and deals with paging.
  59. Output of individual characters and strings to fixed screen-locations
  60. is handled by other procedures.
  61.  
  62.      All this logic deals with output destined for the physical screen.
  63. The built-in C-function putchar() remains the correct procedure for
  64. output of escape-sequences etc. which are in fact intercepted by the
  65. OS or the micro-firmware and interpreted by it rather than being passed
  66. for display.
  67.  
  68.  
  69. 1.2  Keyboard-Handling
  70.   
  71.      There is only one procedure required for reading the keyboard, kbdin();
  72. it is of type char, and returns immediately with or without a character.
  73. It is assumed that the keyboard is buffering any characters which are input
  74. more rapidly than they are read out (though there is no expectation of readout
  75. falling seriously behind input).  Kbdin() does not deal with null characters
  76. (ctl-@), since the return with this is indestinguishable from the return
  77. without a character.  See below for the data which it is expected that
  78. the arrow and F keys will return.
  79.  
  80.  
  81. 1.3  Procedures.
  82.  
  83.      The keyboard/screen procedures which are used by Kermit are as follows
  84. (in all cases, the range of values taken by char variables is assumed to be
  85. from 0 to 255):-
  86.  
  87.   curset(line,col)    position cursor
  88.     char    line, col;
  89.     No return-code.
  90.  
  91.   cursor(sw)        remove/replace cursor
  92.     char    sw;
  93.     If sw = 0, the cursor is removed from the screen; the coordinates
  94.       of the current position continue to be manipulated (by data-output
  95.       or otherwise), even though the cursor is not on display.
  96.     If sw != 0, it is taken as representing a cursor-character to be
  97.       displayed @ the current position. 
  98.     No return-code.
  99.  
  100.   char kbdin()        read char from keyboard
  101.     Returns char in range 1-255, or 0 if no character available.
  102.  
  103.   keyconn()        set keyboard for connect-mode
  104.     Performs any reinitializations needed for connect-mode
  105.       (when the characters to be sent from certain keys may
  106.       differ from those defined below).
  107.     No return-code.
  108.  
  109.   keyinit()        initialize
  110.     Sets up both keyboard and screen (see below).
  111.     No return-code.
  112.  
  113.   keyrest()        restore
  114.     Restores keyboard and screen to their normal state.
  115.     No return-code
  116.  
  117.   outc(ch)        character to screen @ cursor-position
  118.     char    ch;    character
  119.     No return-code.
  120.     A very limited set of control characters are honoured,
  121.     see below for details; others are ignored.
  122.     Characters with the top bit set are displayed as inverse
  123.       video equivalents of those without.
  124.  
  125.   screen(top,bottom)    define scrolling-area
  126.     char    top, bottom;
  127.     No return-code.
  128.     This defines the scrolling area of the screen to be from "top"
  129.       to "bottom" inclusive.  The parameters may be assumed correct,
  130.       except that bottom > 23/24 implies the lowest possible line.
  131.       (Line-numbering 0 - 23/24.)
  132.     The scrolling area is full screen-width.
  133.  
  134.   scroll(n)        scroll screen up/down
  135.     int    n;
  136.     No return-code.
  137.     The scrolling area of the screen is scrolled up or down by the
  138.       number of lines defined by n.  n > 0 implies normal scrolling
  139.       (data moves up); n < 0 is the opposite (data moves down);
  140.       n = 0 is a no-op.  Blank lines are scrolled in at top or bottom,
  141.       so a scroll of more than the size of the scrolling area is 
  142.       a clear-screen.
  143.  
  144.   vtout(loc,ch)        character to screen @ specified position
  145.     int    loc;    screen-position (in HL format as defined below)
  146.     char    ch;    character
  147.     No return-code.
  148.     All characters are treated as printable.  For characters in the
  149.     range 0-31 those defined for the RML 480Z are assumed, but
  150.     any similar set should be acceptable.
  151.  
  152.   vtline(loc,str)    string to screen @ specified position
  153.     int    loc;    screen-postion, as above
  154.     char   *str;    pointer to string
  155.     No return-code.
  156.     All characters treated as printable, as above.  If the string runs
  157.       off the edge, the end is lost.
  158.  
  159.  
  160. 1.4  Cursor Definition.
  161.  
  162.      In defining cursor positions, "HL format" means line*256 + col.
  163. In either HL format or when specified as 2 parameters,
  164. line and column are in range 0-23 (or 0-24) & 0-79 respectively, and refer
  165. to the whole screen, i.e. (0,0) is the top left-hand corner, irrespective
  166. of scrolling-area arrangements.  Validity checks are reduced to a minimum
  167. (taking values > max to be = max and < 0 to be = 0), since Kermit is a
  168. (presumably) developed program.
  169.  
  170.  
  171. 1.5  Control Characters.
  172.  
  173.      CR (0x0d) is defined to move the cursor to the left margin, then move
  174. it DOWN.  LF (0x0a) is defined to move the cursor straight down.  
  175. The UP (0x0b) & DOWN (0x0a) cursor movements cause screen scrolling if they
  176. attempt to go off the scrolling area.  The RIGHT (0x18) & LEFT (0x08) cursor
  177. movements are no-ops if the cursor is already on the margin.  Attempting to
  178. store a character (by outc(ch)) when the cursor is at the right margin
  179. causes a "CR" to the beginning of the next line (with scrolling
  180. if on the bottom line).  DEL (7fH) is defined as a destructive
  181. backspace, i.e. it deletes the character (if any) to the left of the
  182. cursor, then moves the cursor LEFT.  Overtyping an existing character
  183. has no side-effects (i.e. there is no "insert" mode).
  184.  
  185.  
  186. 1.6  Initialization.
  187.  
  188.      Screen initialization implies clearing, homing the cursor to top
  189. left, and setting full-screen scroll.
  190.  
  191.      Keyboard initialization includes switching off any specially-treated
  192. characters such as ctrl-A & ctrl-F.   Kermit uses the arrow-pad and F-keys;
  193. the characters to be returned (other than in connect-mode), with and
  194. without SHIFT, are:-
  195.  
  196.                       unshifted           shifted
  197.                       ---------           -------
  198.         arrow right        0f2H        0d2H
  199.         arrow left        0ecH        0ccH
  200.         arrow up        0f5H        0d5H
  201.         arrow down        0e4H        0c4H
  202.  
  203.         F1            0e2H        0c2H
  204.         F2 (TAB)         88H         88H
  205.         F3            0eeH        0ceH
  206.         F4             9bH        0bbH
  207.  
  208.         DEL/DELT        0x7f        0xff
  209.  
  210.  
  211.  
  212.  
  213. 2.  Communications Interface.
  214.     -------------------------
  215.  
  216.  
  217. 2.1  Manner of Working.
  218.  
  219.      RM Kermit makes no assumptions about whether polled or interrupt-driven
  220. communications are in use.  Procedures return immediately (i.e. they do
  221. not wait for data to be received or transmitted) with a flag indicating
  222. success or error.
  223.  
  224.      In one of the implementations there was a hardware requirement
  225. to quiesce the communications before issuing any commands to the
  226. disk-handling parts of CP/M.  A call s4sleep() was therefore provided,
  227. and is called before all disk operations.  It is a side-effect of any
  228. call to the active procedures s4get(), s4put() or s4reset() to wake up
  229. (un-sleep) the communications.
  230.  
  231.      The interface was designed to be used by other programs as well as
  232. Kermit.  This has resulted in the existence of parameters which are
  233. superfluous, but must be set as shown.  All procedures are type integer,
  234. and return < 1 for an error; success is indicated by 0 or 1.  A call to
  235. any routine when comms are not initialized is an error (-1); in most other
  236. cases the value returned is that of a status-word (see below) which
  237. always has the top bit set.
  238.  
  239.  
  240. 2.2  Procedures.
  241.  
  242.     s4break(len)    /* send "break" to comms line        */
  243.     char    len;        /* duration in sec/8        */
  244.       (this procedure is not expected to return until the break
  245.     has been completely sent.)
  246.  
  247.     s4get(n,buff)    /* read character from comms line    */
  248.     int    n;        /* number of chars available    */
  249.     char    *buff;        /* buffer to receive chars    */
  250.       (in Kermit the value of n is always 1)
  251.       returns 0 if no character available, else # of chars actually
  252.     read (<= n), else error-status.
  253.  
  254.     s4get7(n,buff)  /* read stripped characters from comms line    */
  255.     int    n;        /* number of chars available    */
  256.     char    *buff;        /* buffer to receive chars    */
  257.       as s4get(n,buff) except that it strips the top bit;
  258.     calls to the two may be intermixed.
  259.  
  260.     s4go();        /* open/initialize comms routines    */
  261.       may be called again after s4stop() to reopen comms;
  262.     is a no-op if already open.
  263.  
  264.     s4put(n,buff)    /* write characters to comms line    */
  265.     int    n;        /* number of chars available    */
  266.     char    *buff;        /* buffer containing chars    */
  267.       (in Kermit the value of n is always 1)
  268.       returns 0 if unable to write because line is busy,
  269.     else # of chars actually written (<= n), else error-status.
  270.  
  271.     s4set(options,control); /* set facilities            */
  272.     int    options;    /* facilities-word as defined    */
  273.     char    control;    /* DTR & CTS bits of Z80sio WR5    */
  274.  
  275.     s4sleep();        /* deactivate comms routines        */
  276.       provided for cases where use of disks and communications are
  277.     mutually exclusive, otherwise may be a no-op.
  278.  
  279.     s4speed(code)    /* set speed of comms line        */
  280.     char    code;        /* RML speed-code, 0-9        */
  281.       this routine may be called before s4init().
  282.  
  283.     s4stop();        /* close down comms routines        */
  284.       this routine is a no-op if comms are already stopped
  285.  
  286.     s4test();        /* test status of communications    */
  287.       returns status-word as defined but with top bit set,
  288.     hence always <0.
  289.  
  290.  
  291. 2.3  Returned Status-Word.
  292.  
  293.      This integer was originally a bit-pattern with meanings assigned
  294. to permit careful control of communications.  Kermit only requires that
  295. a negative value (top bit set) should be returned if there is an error. 
  296.  
  297.  
  298. 2.4  Option-Word and Control-Byte.
  299.  
  300.      These were also originally designed with a wide range of possibilities.
  301. The only bits of significance to Kermit are as shown below; all other
  302. bits may be ignored.
  303.  
  304.      Option-word:
  305.          0  -  RTS/CTS flow-control to be used
  306.          1  -  XON/XOFF flow-control to be used
  307.         8/9 -  Parity-Generation on/off
  308.  
  309.      The 2-bit code for parity is:
  310.         0  -  Generation not required
  311.         1  -  Enforce odd parity
  312.         2  -  Enforce even parity
  313.         3  -  Enforce mark parity
  314.  
  315.      The only bit of the control-byte which is significant is bit7;
  316. this is set to 1 to raise DTR or an equivalent signal, 0 to drop it.
  317.  
  318.  
  319. 2.5  Speed-Codes.
  320.  
  321.      The following speed-codes are defined (though not necessarily
  322. all implemented in any given version):-
  323.             
  324.         0  -    110baud (2 stop-bits)
  325.         1  -    300baud
  326.         2  -    600baud
  327.         3  -   1200baud
  328.         4  -   2400baud
  329.         5  -   4800baud
  330.         6  -   9600baud
  331.         7  -  19.2Kbaud
  332.         8  -  40.8Kbaud
  333.         9  -     75baud
  334.  
  335.      There is no provision for split-speed working, nor for
  336. half-duplex line turnaround.  8-bit data is always set, and
  337. 1 stop-bit except at 110baud.
  338.  
  339.  
  340.  
  341.  
  342. 3.  Miscellaneous Interface.
  343.     ------------------------
  344.  
  345.      The following miscellaneous procedures are called by Kermit to
  346. perform system-oriented functions:-
  347.  
  348.  
  349.   cpmgo()        /* return to micro OS        */
  350.     this call is used instead of "exit()" to permit a clean return
  351.     to the micro's operating system after carrying out any
  352.     required housekeeping.
  353.  
  354.   fpanel()        /* debug display        */
  355.     this call is executed after an "ESC-F" break-in to access
  356.     the micros's built-in lowest-level debugging display.
  357.     It may be a no-op if no such facility is available
  358.     or required.
  359.  
  360.   unsigned getram(n)    /* get storage            */
  361.       int  n;            /* # of bytes required    */
  362.     this call is used instead of "malloc()" to obtain dynamic
  363.     storage so that the space occupied by initialization-code
  364.     may be reused; it returns the start-address of the
  365.     block of storage.  If unable to allocate it should
  366.     printf() a failure-message and call cpmgo().  Storage
  367.     once allocated is never released.
  368.  
  369.   netcool()        /* deactivate disk system    */
  370.     this call is made before reading or writing the communications
  371.     line; it would normally be a no-op.
  372.  
  373.   s4env()        /* return environment        */
  374.     this call returns a small integer value to indicate the communications
  375.     environment in which it is running.  The following values
  376.     have been defined:-
  377.         0  -  480Z via SIO4
  378.         1  -  480Z via IDC
  379.         2  -  Nimbus via Data Comms Controller (n.y.i.)
  380.         3  -  Nimbus via Aux port
  381.         4  -  Nimbus via Piconet
  382.         5  -  480Z or Nimbus via RML Network (n.y.i.)
  383.         6  -  non-standard
  384.      (Any user extending this table will have to amend the entries
  385.     in arrays locations[] and fuzz[] in RMKDATA.C)
  386.  
  387.      The versions of these routines in file RMKNIMB.C should be suitable
  388. for most straightforward micros.
  389.  
  390.  
  391.  
  392. 4.  Data Items.
  393.     -----------
  394.  
  395.      There is no absolute need to change any of the texts displayed.
  396. The versions found in files RMK480Z.C and RMKNIMB.C (for CP/M and
  397. MSDOS systems respectively) may well be acceptable; the examples
  398. below are those from the Nimbus version.
  399.  
  400.      Data items which should be supplied for display are as follows:-
  401.  
  402. char head1[]        text-string to identify program, e.g.
  403.         "  RM  NIMBUS  Kermit  File  Transfer  Program,";
  404.  
  405. char prompt[]        normal prompt to be displayed by RM Kermit (there is
  406.     no ability to change this dynamically), preceded by CR, e.g.
  407.         "\rKmNimbus";
  408.  
  409. char eprompt[]        special prompt to be displayed after ESC break-in, e.g.
  410.         "\rKmF4> ";
  411.  
  412. char backto[]        final message to be displayed when Kermit terminates, e.g.
  413.         " OK - back to MSDOS; ";
  414.  
  415.      If these texts are altered, it is recommended that their lengths should
  416. not be extended.
  417.  
  418.  
  419.     *******************************************************
  420.