README

   1
   2 The goal of this assembler is to eventually not be simply an M68K
   3 assembler, but to be relatively easily retargetable.  Also, this
   4 assembler should be callable from other CL applications, as well as
   5 executable as a stand-alone program.
   6
   7 The code's not so clean right now, maybe, but I've been using it for
   8 various Atari ST projects for a little while now to great personal
   9 satisfaction.
  10
  11
  12 The a.out object format supported here and by st-linker is not really
  13 quite exactly a.out.  It's close, though.
  14
  15
  16 To build this from scratch, you'll need to do something like:
  17 (in the m68k-asm directory)
  18
  19 CL-USER> (asdf:oos 'asdf:load-op :lalr-parser-generator)
  20 CL-USER> (load "m68k-grammar")
  21 CL-USER> (with-open-file (stream "parser.lisp" :direction :output)
  22             (lalr:make-parser m68k-asm::*m68k-asm-grammar*
  23                               :package (find-package "M68K-ASSEMBLER")
  24                               :stream stream))
  25
  26 I'm going to make that a bit cleaner at some point.
  27
  28
  29
  30 Things to add in the grammar/parser/lexer:
  31
  32 Support for ' (single ASCII character?) -- only because the
  33         book I have says it's part of Motorola's standard.  Should it
  34         behave like double-quotes or what?
  35 Support for floats (once FPU instructions are supported).
  36
  37
  38 Things to add in the assembler:
  39
  40 Checking ranges of types, signed indices, etc.
  41         Also, type checking information stored in the symbol table.
  42 Output listings (with cycle counts, et cetera).
  43 Support for later chips in the m68k line, and enabling/disabling
  44         allowance of their added instructions.
  45 Change lookup tables so that on load, they get converted to hash
  46         tables or whatever's appropriate. [half-done]
  47 Nifty local labels a-la GNU as or similar.  (0f, 1b, etc)
  48 BRA.S (currently you have to say BRA.B).
  49 CL-style macros?  (that would be cool!)
  50         The natural thing to do is join this with my other experiment
  51         (assembly lisp) and use a sexp intermediary form still
  52         accessible to the user which would be more amenable to
  53         macrology.
  54 Debugger info.
  55 Output in object formats other than A.OUT.
  56 Optimizations/data flow analysis.
  57 Optional lispy object format.  (see st-linker README)
  58 Stuff to make guesses about pairs of MOVEM instructions at head of
  59         function and just before RTS/RTE, and warn the user if they
  60         mismatch.
  61 Cleaner abstract syntax.
  62
  63
  64 THINGS TO DO BEFORE RELEASE
  65
  66 - remove debugging output.
  67 - add a decent warning/error display and logging system.
  68 - compile list of known issues, try to resolve.
  69 - put together a basic automated test suite.
  70   (once object format has settled down, start a set of regression files,
  71    with sane output verified by hand; also, feed smaller files that
  72    should deliberately provoke certain conditions in, watch for those
  73    conditions.)
  74 - skim all XXXs.
  75 - once a better warning system is in place, allow routines like
  76   MODIFIER-BITS to guess the size of underspecified operations, and warn
  77   about them at suitable warning levels.
  78 - test with sourcer68 output of various files.
  79 - Things to test about relocation:
  80         are 8-bit indirect displacements being relocated correctly?
  81         verify all possible relocation combinations.
  82 - Update dependencies in ASDF file so that it compiles without warnings.
  83 - *last-label* feels like a hack.  See if there's an alternative.
  84 - DC needs some serious cleanups.
  85 - undo some of the intentional braindamage induced to make us closer
  86   to devpac.
  87 - various pseudo-ops need to work on list of operands rather than
  88   single operand.
  89 - stifle horrible potential bug with MOVEQ optimizations and negative
  90   numbers/sign extension.
  91 - add basic sexp mode.
  92
  93
  94 THINGS TO PUT IN TEST SUITE
  95
  96 - conditional compilations;
  97 - ensure directives like ALIGN and EVEN don't emit unnecessary padding;
  98 - random instruction streams tested against disassembly;
  99 - test that * (as comment) and * (as multiply) are being handled correctly;
 100 - test (known broken) MOVE->MOVEQ sign extension bug;
 101 - extensive macrology;
 102 - files that end without newlines, that have funny characters in them, etc.
 103
 104
 105 KNOWN ISSUES
 106
 107 - macro parameters are broken.  At least, <foo> style ones are still
 108   broken.  Also, \n always expands to an absolute symbol, so you can't
 109   use a register.  [assembler]
 110 - size output is broken if ORG is used.
 111 - Unfinished pseudo-ops: (all are quite easy)
 112         EQUR
 113         DCB
 114         END
 115         IFxx (IFEQ and IFNE are already done)
 116 - branch-displacement-bits will behave badly in some unusual situations.
 117   It's ugly and needs to be cleaned up.
 118
 119
 120 KNOWN MAJOR INCOMPATIBILITIES WITH DEVPAC
 121
 122 These are things which aren't likely to change soon.
 123
 124 Macros:
 125
 126 - we don't support < or > embedded in macro parameters which are
 127   already wrapped in < and >.  (eg: "<foo>>>>2>" => "foo>>2") [lexer]
 128
 129
 130 ENHANCEMENTS FROM DEVPAC
 131
 132 - We support EXTERN/GLOBAL as synonyms for XREF/XDEF,
 133   respectively.  Also ALIGN as a simple version of CNOP.
 134