[movitz-cvs] CVS update: ia-x86/README

[Frode Vatvedt Fjeld]

Update of /project/movitz/cvsroot/ia-x86
In directory common-lisp.net:/tmp/cvs-serv29444

Modified Files:
	README 
Log Message:
*** empty log message ***
Date: Sun Jan 30 03:35:16 2005
Author: ffjeld

Index: ia-x86/README
diff -u ia-x86/README:1.1 ia-x86/README:1.2
--- ia-x86/README:1.1	Sat Jan 29 08:33:31 2005
+++ ia-x86/README	Sun Jan 30 03:35:16 2005
@@ -10,7 +10,7 @@
 ## Author:        Frode Vatvedt Fjeld <frodef at acm.org>
 ## Created at:    Sat Jan 29 16:48:42 2005
 ##                
-## $Id: README,v 1.1 2005/01/29 16:33:31 ffjeld Exp $
+## $Id: README,v 1.2 2005/01/30 11:35:16 ffjeld Exp $
 ##                
 ######################################################################
 
@@ -22,7 +22,7 @@
 the Movitz compiler. The following documents the most interesting API
 operators for this package.
 
-A few terms requires explanation. A "proglist" is a representation of
+A few terms requires explanation. A "program" is a representation of
 an assembly program that is reasonably convenient to work with for
 humans. This is a list, whose elements are either a symbol that
 represents a label, or a list that represents an instruction.  The
@@ -31,10 +31,70 @@
 by 1" (more on this syntax below). However, instructions are also
 represented internally ia-x86 by instances of the various subclasses
 of the "instruction" standard-class, and lists of such objects are
-also someplaces referred to as proglists.
+referred to as "proglists".
 
 
 			       Assembly
 
+The function read-proglist reads a program into proglist form, which
+is typically the first step in producing machine code. This function
+(and its helper functions, in read.lisp) defines the human-readable
+syntax for assembly programs. This is an example program (or rather, a
+lisp function that produces an assembly program):
+
+  (defun mkasm16-bios-print ()
+    "Print something to the terminal.  [es:si] points to the text"
+    `((:movzxb (:si) :cx)
+      (:incw :si)
+      (:movb #xe :ah)
+      (:movw 7 :bx)
+     print-loop
+      (:lodsb)
+      (:int #x10)
+      (:loop 'print-loop)
+      (:ret)))
+
+I personally tend to use keywords for instruction names, although the
+instructions are recognized by name rather than identity, so any
+package will do. Labels, however, are recognized by identity. Label
+references are on the form (quote <label>), so that the loop
+instruction above will transfer control to the print-loop label two
+instructions before it. Indirect memory references are writen by
+placing the pointer inside parens, such as in the first movzxb above.
+If the first element of an instructon is a list (rather than an
+instruction name), this is interpreted as a list of instruction
+prefixes (such as REP, LOCK, etc.).
+
+This is a more-or-less exact description of the syntax:
+
+       program ::= (<sexpr>*)
+
+         sexpr ::= ( <expr> ) | <label> | (% <inline-data> %) | (:include . <program>)
+          expr ::= <instro> | ( { <prefix> } ) <instro>
+        instro ::= <instruction> { <operand> }
+
+       operand ::= <concrete> | <abstract>
+
+      concrete ::= <immediate> | <register> | <indirect>
+     immediate ::= <number>
+      register ::= eax | ecx | ...
+      indirect ::= ( iexpr )
+         iexpr ::=   <address>
+                   | (quote <label>)
+                   | <segment> <address> 
+                   | pc+ <offset>
+                   | pc  <address>
+                   | { (quote <label>) } <offset> <scaled-register> <register>
+     scaled-register ::= <register> | ( <register> <scale> )
+               scale ::= 1 | 2 | 4 | 8
+             address ::= <number>
+              offset ::= <signed-number>
+
+      abstract ::= (quote <absexpr>)
+       absexpr ::= <label> | <number> | append-prg
+    append-prg ::= program
 
+        prefix ::= <segment-override> | (:size <size>)
 
+The function proglist-encode takes a proglist and produces
+machine-code in the form of e.g. a vector of 8-bit bytes.