util/int/switch/READ_ME

   1 # $Id: READ_ME,v 2.3 1994/06/24 10:49:57 ceriel Exp $
   2
   3 This directory contains two programs:
   4
   5 mkswitch:
   6         C program, necessary for regenerating the giant switch
   7         needed for the disassembly function of the interpreter,
   8         which (still) works with Operand access method 2
   9         (Intelligent Routines) as described in "The EM
  10         interpreter".
  11
  12 mkiswitch:
  13         C program, necessary for regenerating the giant switch
  14         needed for finding the correct instruction handling routine
  15         for each opcode.  It works with Operand access method 3
  16         (Intelligent Calls) as described in "The EM interpreter".
  17         It constructs the operand of the instruction and passes
  18         it to the appropriate routine with the operand as
  19         argument.
  20
  21 The first program reads an input file which holds the interpreter
  22 opcode table (as shown in the [IR-81] report appendix B),
  23 and creates an output file which contains an enormous switch
  24 file.  This switch has entries for each possible opcode.  It's
  25 possible to supply a third filename, which is the name of file
  26 where all functions will be stored.  This is necessary if a new
  27 function implementation is needed.
  28
  29 The first argument to mkswitch is the prefix to be used in the
  30 generated function names.  For the interpreter proper this prefix
  31 is  Do.
  32
  33 The input file contains lines in the following format:
  34
  35         Mnemonic Flags Count First-number
  36
  37 The created switch file will contain a switch, with each case
  38 having one of the following formats (? is the opcode):
  39
  40         1) case ?: DoAz();
  41         2) case ?: DoBm(val);
  42         3) case ?: DoCs(hob, wsize);
  43         4) case ?: DoDXY(wsize);
  44
  45 Ad 1)   This format shows that the corresponding opcode does not
  46         have an argument.  Often the operand is popped from the
  47         stack.
  48
  49         e.g. DoNOPz(), this performs the NOP instruction.
  50
  51 Ad 2)   This is the format for a mini.  There is one implicit
  52         argument (I) .
  53
  54         e.g. DoLOCm(1), this is the LOC 1 instruction.
  55
  56 Ad 3)   This format corresponds with a shortie.  There is an implicit
  57         argument (high order byte), and a one byte text argument
  58         (low order byte).  W equals 'wsize' (if a word multiple),
  59         otherwise it equals '1'.  H is the value of the high
  60         order byte.
  61
  62         e.g. DoLOEs(2, wsize), these are all LOE instructions,
  63         with all addresses in the range:
  64                 (512 * wordsize) . . (767 * wordsize).
  65
  66 Ad 4)   This format is used for opcodes with 2 or more text arguments,
  67         and no implicit arguments.  There are 6 types:
  68
  69         XY = l2: two byte negative or positive text argument.
  70         XY = n2: two byte negative text argument.
  71         XY = p2: two byte positive text argument.
  72         XY = l4: four byte negative or positive text argument.
  73         XY = n4: four byte negative text argument.
  74         XY = p4: four byte positive text argument.
  75
  76         W equals 'wsize' (if a word multiple), otherwise it equals 1.
  77
  78         e.g. DoLDLp2(wsize), these are all LDL instructions, with
  79         negative local offsets, which are word multiples.
  80
  81
  82 When two file arguments are given to mkswitch (input file and output file),
  83 only the switch is generated.  If an additional third file name is
  84 given (another output file), this file is filled with all function
  85 calls in such a manner that mkfuncs will generate new function files.
  86
  87 Mkfuncs expects two arguments, an input file generated by
  88 mkswitch and the name of a directory where the new function
  89 files are stored.  These files (15) each represent one group (as
  90 proposed in [IR-81] sec 11.3) of instructions.  Each file will
  91 contain all functions needed to implement that specific group
  92 of instructions.  The functions will only contain a logging
  93 message, and a call to newPC() which is necessary to skip the
  94 arguments.  The names of the generated files are: do_XXX.c, where
  95 XXX is the name of the corresponding instruction group.
  96
  97 (Note: these remarks about mkfuncs are probably outdated now,
  98 since mkfuncs has disappeared. -rbf)