                                                                                         
                       --=-=========================-=--
                            PC-DRAGON 6809 EMULATOR
                       --=-=========================-=--
                                       
                       Version 2.06 - Source Code Notes
                         Emulator Copyright 1993-2000
                                By Paul Burgin
                        Disk Module Copyright 1998-2000
                       By Stewart Orchard & Paul Burgin
                            http://browse.to/dragon
                                       
 Thankyou for using PC-Dragon, especially if you're a registered user.  These
 notes accompany the source code for the PC-Dragon emulator. Instructions for
 using  the emulator are not included here; for these please refer to  either
 PCDRAGON.TXT  (plain  text  reference  manual)  or  PCDRAGON.PS  (postscript
 version  of  reference manual). Please also see the additions and amendments
 applicable  to  this latest release of the emulator which can  be  found  in
 files  README.TXT  (general  notes), DISKS.TXT (disk  emulation  notes)  and
 VCOPY.TXT (instructions for using the VCOPY utility).
                                                   
 IMPORTANT:  Please note that the following restrictions apply to the  source
 code:
                                                   
     All  users  are granted permission to modify and recompile  the  source
      code for personal use.
                                                   
     Permission  is also granted to distribute executables which  have  been
      built from modified versions of the source code so long as this is done
      on a non-profit basis. If you wish to distribute derivative versions of
      PC-Dragon then you must clearly identify your version as such and  must
      not remove the original copyright messages. Please take all  reasonable
      steps to ensure that it is unlikely your modified emulator distribution
      will be confused with the authorised freeware distribution of PC-Dragon.
                                                   
     Redistribution of the freeware version of the emulator source  code  is
      permitted, but only as a complete and unmodified archive. Files in  the
      archive must not be altered in any way. Additionally, files must not be
      removed from or added to the archive.
                                                   
     Redistribution of the registered version of the emulator source code is
      not permitted, but copying and backup for personal use is fine.
                                                   
     Distribution of the emulator source code for any other purpose (outside
      of the terms of these restrictions) may be permitted at the  discretion
      of (and by prior arrangement with) the author(s).
                                                   
 The  above restrictions do not apply to KEY.H and KEY.ASM, which are  freely
 distributable.
 
 The  following  notes  aim to annotate the source code.  It  has  been  made
 available in response to the requests from people interested in the workings
 of the emulator. I hope therefore that the public release of the source code
 will  help  to  answer  the questions and increase  your  enjoyment  of  the
 emulator.
 
 The  source code is written in C and is suitable for compilation with either
 Borland  Turbo C++ or Borland C++. It has mostly been developed under  Turbo
 C++  IDE  V3.1  running on a 486DX-33 (in this configuration  a  full  build
 consists of approximately 43,300 lines of code and takes just over a  minute
 to complete).
 
 PC-Dragon  now supports long filenames when run from an MS-DOS prompt  under
 Windows  95/98. This support is implemented through my long filename library
 which  is  included  here in the form of header file LFN.H  and  the  medium
 memory  model library file LFN_M.LIB. Instructions for using the LFN library
 are  also  included  -  please see READ_LFN.TXT for details.  The  full  LFN
 library  package (including portable source code) can be downloaded from  my
 website  at address http://public.logica.com/~burginp/x86.html (should  this
 URL   become   obsolete   please   follow   the   appropriate   links   from
 http://browse.to/paul).
 
 PC-Dragon  also  makes use of a customised version of  a  freeware  keyboard
 handler  written  by  Lee Hamel. This handler consists of  KEY.ASM  and  the
 header  file  KEY.H.  It is used to take control of INT9  when  'Real  Mode'
 keyboard emulation is selected. It is written in 8086 assembler suitable for
 Borland  Turbo Assembler. The associated object file KEY.OBJ (compiled  with
 TASM  V2.02) is included here for the benefit of anyone without access to  a
 suitable assembler.
 
 Overall, the emulator source code is composed of 12 header files and 19 code
 modules.  I  should  point out that it is no work of art. PC-Dragon  started
 life  in  1993  as an experimental prototype and grew from there;  over  the
 years  it  has  been  quite  extensively  chopped,  changed,  expanded   and
 redesigned  according  to need. This colourful history  may  be  evident  in
 places  in  the source code, although I have always tried hard to  make  the
 components fit together.
 
 The source code contains quite a few comments to explain the implementation,
 although they are scattered more liberally in some modules than others.  All
 files require a TAB size of 4 characters.
 
 The  header files and code modules are listed below. Each module  is  either
 related  to  a  peripheral which is emulated by PC-Dragon, or implements  an
 internal subsystem of the emulator.
 
 PC-Dragon Header Files
 ----------------------
 
 6809CPU.H  Definitions of 6809 instructions and addressing modes.
 6809REGS.H Declarations and definitions for 6809 registers.
 BUILD.H    Public definitions and build options.
 DOIO.H     Definitions used for the DOIO instruction.
 EXTERN.H   External function and variable prototypes.
 KEY.H      Keyboard interrupt and scan code definitions.
 MACROS.H   Common functions which are expanded in-line.
 SNAPSHOT.H PAK format definitions.
 TYPES.H    Miscellaneous type definitions.
 DOSCART.H  External function prototypes for the disk module.
 LFN.H      Header file for the long filename library.
 LFN2.H     Header file for an additional LFN function.
 
 PC-Dragon Modules
 -----------------
 
 6809TAB    Table of data for 6809 instructions.
 CASSETTE   Cassette and cartridge emulation.
 DEBUGGER   Built-in debugger and disassembler.
 DIALOGUE   Functions for dialogue boxes, menus and info screen.
 DRAGON     Fetch-execute cycle, 6809 instructions, memory access.
 JOYSTICK   Functions for joystick emulation and mouse support.
 KEYBOARD   Functions for keyboard emulation and internal buffers.
 KEYWORDS   Tables of defaults for the programmable keys.
 MOTOROLA   Functions for reading S19 format files.
 SAMPIAS    SAM and PIA chip emulation.
 SERVICES   Functions which provide the emulator services.
 SNAPSHOT   Functions for reading and writing snapshots.
 TEXTVIEW   Stand-alone text viewer utility.
 TITLE      Functions to display the start-up and exit messages.
 VIDEO      Text and graphics screen emulation.
 KEY        Replacement handler for keyboard interrupt.
 DOSCART    Disk emulation.
 LFN_M      Long filename library.
 LFN2       Contains an additional LFN function.
 
 In  order  to  protect the emulator copyright, module TITLE is  supplied  in
 object  form  in  the freeware version of this package, but is  supplied  as
 source code in the registered version of this package.
 
 The  original  project file DRAGON.PRJ is also included. This file  contains
 the  compiler  options  required to rebuild the  emulator  using  a  Borland
 compiler.  If  you use a different compiler or are otherwise unable  to  use
 this  file then you must ensure that you compile the software for the MEDIUM
 memory  model  and  enable  support for the  graphics  library.  When  using
 DRAGON.PRJ  you  will initially need to re-configure the locations  of  your
 compiler  INCLUDE  and LIBRARY directories (and also the  transfer  path  to
 Turbo  Assembler  if using KEY.ASM; alternatively remove  KEY.ASM  from  the
 project and add KEY.OBJ instead).
 
 To  link the object files you will also require a far segment version of the
 EGA/VGA graphics driver in object form. To create this file use the compiler
 supplied  utility  BGIOBJ.EXE  (previously  BINOBJ.EXE  for  older   Borland
 compilers)  together  with  the  /F option  and  the  graphics  driver  file
 EGAVGA.BGI.  This utility and the graphics driver file can be found  in  the
 BGI  sub-directory  off the directory in which you installed  the  compiler.
 Typically  you should type "BGIOBJ /F EGAVGA" since the default  values  are
 fine for all of the other parameters. The output from this conversion should
 be EGAVGAF.OBJ, which should be copied to your PC-Dragon source directory.
                                                   
 The  fetch-execute section of DRAGON.C may seem quite erratic. It uses a lot
 of  embedded declare blocks and temporary register variables, but  there  is
 good  reason  for this. This particular section has been coded in  this  way
 because  it  appears to generate more efficient machine code. For  this  and
 other  time-critical sections of the software I have studied the disassembly
 of  the  machine  code  generated by the compiler,  and  from  this  I  have
 optimised  the  C  source  code  as  best I  can.  Suggestions  for  further
 optimisations are, of course, most welcome!
 
                                                                       16/1/0

