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

[Frode Vatvedt Fjeld]

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

Modified Files:
	README 
Log Message:
*** empty log message ***
Date: Sun Jan 30 06:54:33 2005
Author: ffjeld

Index: ia-x86/README
diff -u ia-x86/README:1.2 ia-x86/README:1.3
--- ia-x86/README:1.2	Sun Jan 30 03:35:16 2005
+++ ia-x86/README	Sun Jan 30 06:54:33 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.2 2005/01/30 11:35:16 ffjeld Exp $
+## $Id: README,v 1.3 2005/01/30 14:54:33 ffjeld Exp $
 ##                
 ######################################################################
 
@@ -67,6 +67,8 @@
 
 This is a more-or-less exact description of the syntax:
 
+---------------------------------------------------------
+
        program ::= (<sexpr>*)
 
          sexpr ::= ( <expr> ) | <label> | (% <inline-data> %) | (:include . <program>)
@@ -96,5 +98,40 @@
 
         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.
+machine-code in the form of e.g. a vector of 8-bit bytes. A typical
+usage would be this:
+
+  (proglist-encode :octet-vector :16-bit #x7c00
+                   (read-proglist (mkasm16-bios-print)))
+
+The first agument, :octet-vector, requests that the result be in the
+form of a vector of octets. The second argument says to prodce machine
+code for the 16-bit mode of x86. Next is the address to assume the
+code is located in memory (if the program is position-independent,
+just pass zero). Finally, there is the proglist to be encoded to
+machine code. Additionally, the keyword argument :symtab-lookup can
+provide a function that proglist-encode will use to map (otherwise
+undefined) labels to integers. The primary return value is the byte
+vector, while the secondary return value is an (assoc) symbol-table:
+
+  IA-X86(7): (proglist-encode :octet-vector :16-bit #x7c00
+                              (read-proglist (mkasm16-bios-print)))
+  => #(#xf #xb6 #xc #x46 #xb4 #xe #xbb #x7 #x0 #xac ...)
+  => ((PRINT-LOOP . #x7c09))
+
+
+Another operator that can be useful for interactive and experimental
+use, is the macro "asm" which encodes a single instruction. This can
+be used e.g. to verify syntax or the encoded size of an instruction:
+
+  IA-X86(8): (asm :movl :eax (:ebx 1))
+  => #c(#x894301 #x3)
+
+The return value is a complex, whose real component is the binary
+encoding of the instruction, and the imaginary component is the number
+of bytes.
+