home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 4 / Apprentice-Release4.iso / Languages / MacQForth 1.0 / documentation / Discussion next >
Encoding:
Text File  |  1995-03-15  |  11.0 KB  |  205 lines  |  [TEXT/ALFA]
  1. r.  Most are 
  2.    accessed during QForth's initialization and contain information to 
  3.    trick QForth into thinking it is running on an Apple IIe, or are 
  4.    simply set to RTS ($60) to bypass screen and text initialization.
  5.    
  6.    The only monitor subroutines used are COUT ($FDED), CROUT1 ($FD8B), 
  7.    and GETKEY ($FD0C).  These locations contain traps that cause the 
  8.    simulator to execute a Forth word to implement the desired function.  
  9.    In addition, I included a trap for $FDDA to output the accumulator as 
  10.    two hexadecimal digits.
  11.    
  12.    The traps are:
  13.    
  14.    $FB  -  get a key from the keyboard to A
  15.    $F7  -  output return
  16.    $F3  -  output A as a character
  17.    $C7  -  output A as a two hex digits
  18.    $CF  -  invoke system monitor, do NOT use this alone!  Use JSR$FFF0.
  19.    $E7  -  clear the screen (used in $C300)
  20.    
  21.    
  22.    Each of these subroutines alters the accumulator (except for CROUT1 
  23.    which issues a return).  If desired, these locations could be 
  24.    altered to jumps to user written input and output routines.  For example,
  25.    if you wanted each character output along with its ASCII code:
  26.    
  27.    $FDED : 4C
  28.    $FDEE : 00
  29.    $FDEF : 03     ( jump to user output routine at 300 )
  30.    
  31.    $0300 : F3       output the character in A
  32.    $0301 : A8       TAY , put A in Y to keep it
  33.    $0302 : A9 20    LDA #$20 , load a space
  34.    $0304 : F3       output it
  35.    $0305 : 98       TYA , restore A
  36.    $0306 : C7       output A as hex digits
  37.    $0307 : F7       output a return
  38.    $0308 : 60       return
  39.       
  40.  
  41.    
  42. Special additions
  43. -----------------
  44.  
  45.    To spice things up a bit, I included several additional traps.
  46.    
  47.    
  48.    Graphics
  49.    --------
  50.    
  51.       A single graphics pen, whose coordinates are _independent_ of the 
  52.       cursor coordinates, is used for line drawing.  While available to 
  53.       machine code programs, they read their values from the QForth 
  54.       stack.  See the file ASSEMBLY AND QFORTH for help on interfacing 
  55.       machine language programs and QForth.
  56.       
  57.       traps,
  58.       
  59.       $EF  -  set pen to X,Y on stack
  60.       $EB  -  draw a line from current position to X,Y on stack
  61.       $E3  -  set the drawing color to N on stack, oldstyle Quickdraw
  62.               (presently not quite right, some colors absent)
  63.       $D7  -  plot a point at X,Y on stack
  64.       
  65.    
  66.    Mouse and Random numbers
  67.    ------------------------
  68.       
  69.       A trap exists that will push the current mouse position and button 
  70.       status (0 or -1) on the QForth stack.  Other traps are used to get 
  71.       random numbers.  The $CB trap will be of most use to machine 
  72.       language programs.
  73.       
  74.       traps,
  75.       
  76.       $D3  -  put the mouse position and button status on the stack
  77.       
  78.       $CB  -  put a 16-bit random number in $FF8E and $FF8F
  79.       $BF  -  put a random number from 0 - N-1 on stack, N from stack
  80.       
  81.       
  82.    Startup word
  83.    ------------
  84.    
  85.       It is possible to set a startup word that will be executed when a 
  86.       memory image is loaded.  The address of the word needs to be on the 
  87.       QForth stack when the trap is executed.  The address can be that of 
  88.       a machine language program.
  89.       
  90.       trap, $C3  -  set the address on the stack to the startup word
  91.       
  92.       
  93.  
  94. ProDOS and the Mac
  95. ------------------
  96.  
  97.    QForth access the disk in the way most Apple IIe programs do, through 
  98.    the ProDOS machine language interface (MLI).  The MLI consists of a 
  99.    series of single byte commands followed by the appropriate command 
  100.    parameters.  All ProDOS interaction takes place through these 
  101.    parameters.  A typical MLI command sequence is,
  102.    
  103.    20 00 BF   -   call MLI, JSR $BF00
  104.    C8         --> open a file command
  105.    03         --> number of parameters
  106.    00 00      --> pointer to filename string (<length><text> format)
  107.    00 00      --> pointer to input/output buffer to hold data
  108.    00         <-- reference number for the file (like a FILE ptr in C)
  109.    
  110.    where the --> is for information sent to ProDOS and <-- is for 
  111.    information returned by ProDOS.  Program execution continues with the 
  112.    instruction just beyond the last command parameter.  If the Carry flag 
  113.    is set, or the Zero flag, an error occured and the code is returned in 
  114.    the accumulator.  Normally a it is ProDOS error code, but in this case the 
  115.    error is the absolute value of the corresponding Mac error code, i.e. 
  116.    if the file is not found a 43 decimal is in the accumulator.  Zero is 
  117.    no error.
  118.    
  119.    The following ProDOS commands are supported by MacQForth:
  120.    
  121.    $C0  -  create
  122.    $C1  -  destroy
  123.    $C8  -  open
  124.    $CA  -  read
  125.    $CB  -  write
  126.    $CC  -  close
  127.    $CE  -  position
  128.    $65  -  quit
  129.    
  130.    See the file ASSEMBLY AND FILES in the ASM6502 folder for detailed 
  131.    information about using ProDOS commands from within a machine language 
  132.    program.
  133.    
  134.    
  135.    
  136. Keyboard and Screen I/O
  137. -----------------------
  138.  
  139.    To text, the MacQForth screen is divided into 23 lines of 80 
  140.    characters.  The QForth words  cv  and  ch  are used to set the 
  141.    vertical and horizontal cursor positions.  They take their values from 
  142.    the QForth stack.  Again, see ASSEMBLY AND QFORTH for more information.
  143.    
  144.    
  145.    
  146. System Monitor
  147. --------------
  148.  
  149.    The system monitor program (invoked by '65520 execute') exists as a
  150.    hybrid, part 6502 code and part Mops.  This was necessary because of 
  151.    the way the Mac handles events, especially key events.  The normal 
  152.    QForth input routine is used and Mops evaluates the input.  NEVER use 
  153.    the $CF trap alone, but use a JSR$FFF0 whenever you want to start the 
  154.    system monitor.  The A register and Z flag are altered.
  155.  
  156.    Commands are (case and space insensitive),
  157.    
  158.      L <addr>     --  Disassembled listing starting at <addr>
  159.      L            --  Disassembled listing starting at last address + 1
  160.      S <addr>     --  Substitute memory, return leaves it unaltered, '!' ends
  161.      X <addr1>.<addr2> --  Hex dump from <addr1> to <addr2>
  162.      Q            --  Quit, return to caller
  163.  
  164.  
  165. Final Word
  166. ----------
  167.  
  168.    MacQForth offers much in the way of freedom.  It is not a development 
  169.    platform, and certainly will not win any speed contests.  But it is 
  170.    well suited to learning Forth and to learning about old 8-bit 
  171.    microprocessors.  I sincerely hope that some find it half as much fun 
  172.    to use as it was to write!
  173.  
  174.    
  175. R. Kneusel, March 1995.
  176.  
  177.    
  178. ================================================================================
  179.  
  180. Bibliography
  181.  
  182.  
  183.   These are the book I used as references for this project.  I doubt that 
  184.   they are still available, though.
  185.   
  186.   
  187.   _Apple IIe Technical Reference Manual_, Addison-Wesley, Mass., 1985.
  188.   
  189.      Information on the "new" 65C02 opcodes and addressing modes not 
  190.      found in Scanlon's book.
  191.   
  192.   
  193.   Little, Gary B. _Apple ProDOS: Advanced Features for Programmers_, 
  194.          Brady Communications, Maryland, 1985.
  195.   
  196.      About the ProDOS MLI commands.
  197.      
  198.          
  199.   Scanlon, Leo J. _6502 Software Design_, Howard Sams & Co., 
  200.          Indianapolis, 1980.
  201.      
  202.      Technical information about the 6502, its instructions, and 
  203.      addressing modes.
  204.     
  205.