changed documentation to follow recent changes
Sat Nov 3 14:39:17 PDT 2007 Ties Stuij <ties@stuij.se>
* changed documentation to follow recent changes
diff -rN -u old-armish/README new-armish/README
--- old-armish/README 2014-08-01 15:29:43.000000000 -0700
+++ new-armish/README 2014-08-01 15:29:43.000000000 -0700
@@ -1,4 +1,6 @@
-** Armish - An assembler quite contraire
+
+
+*** Armish - An assembler quite contraire
Armish is the Amish of the computer-world. The Amish plough forth through life
under the twin burden of an extreme religion and an accompanying extreme way of
@@ -16,6 +18,7 @@
know... You never know, da#@^$it!!
+
** License - LLGPL, see the LICENSE file
** Authors
@@ -24,20 +27,17 @@
- Ties Stuij
+
** Concept
-Armish is an assembler like any other. The main difference is that it doesn't
-read from file. It's meant to just spit out a list of bytes by way of the
-function `assemble'. Just feed it some forms and it spits out opcodes
-surrounded by parenthesis. The idea is that the client code can easily build
-higher abstractions by abstracting away code generated by individual calls to
-`assemble'. That's the idea anyway. See the Liards library, which compiles
-these calls to assemble down to a file format fit to be run on a Nintendo DS,
-for an example of it's use.
-
-It's Armish's aim is to be a bit on the general side but the latest processors
-are not (yet/ever) supported. It should be usable for arm architectures 3
-through 5 though (till arm9). Complaints about missing features are welcome.
+Armish is an assembler like any other. With parenthesis around the instructions.
+It's Armish's aim is to be a bit on the general side. It assembles arm and thumb
+code, but new features of the latest processors are not (yet/ever) supported.
+They're quite backwards compatible though, those processors, last time I checked.
+Armish should be usable for arm architectures 3 through 5 (till arm9), and of those
+just the core. No enhanced dsp instructions or such. Complaints about missing
+features are welcome. See Liards, for a lib that actually uses it.
+
** Installation
@@ -54,6 +54,7 @@
wired into your asdf machinery together with Armish, just fire it up.
+
** Testing
You can check if (a subset of) all the standard instructions work by first
@@ -83,6 +84,7 @@
file that can help with debugging.
+
** Exported functions
- assemble - Assembles forms into a list of opcodes for specified chip and
@@ -138,7 +140,9 @@
- aligned - returns the next bytes byte aligned address. Defaults to four if
-bytes is not supplied syntax: (aligned address &optional bytes)
+bytes is not supplied
+
+syntax: (aligned address &optional bytes)
example usage: (aligned (length '(1 2 3 4 5))) ==> 8
@@ -149,6 +153,18 @@
helpers.lisp for functions that might aid you.
+- set-armish-string-encoding - sets the armish string encoding. Armish passes
+the encoding to the arnesi string-to-octets fuction, which tries to do the right
+thing. From the documentation: "We gurantee that :UTF-8, :UTF-16 and :ISO-8859-1 will
+work as expected. Any other values are simply passed to the underlying lisp's
+function and the results are implementation dependant.
+
+syntax: (set-armish-string-encoding :keyword)
+
+example usage: (set-armish-string-encoding :ISO-8859-1) ==> :ISO-8859-1
+
+
+
** Instruction syntax
Basically this assembler follows the arm assembler syntax but then lispified:
@@ -167,8 +183,10 @@
test cases in the test.lisp file.
+
** Assembler format, features and conventions
+
* Directives
code16 - assemble as thumb code32 - assemble as arm
@@ -191,16 +209,26 @@
(dword byte &rest bytes) - define one or more 64 bit words (quad byte &rest
bytes) -define one or more 64 bit words
+(bin byte-size bin-list) - a more general directive than the previous ones.
+First specify how many bytes of storage space the data items of the bin-list
+should take, then supply the list itself. For example assembling
+(bin 2 (1 2 3 4)) results in (1 0 2 0 3 0 4 0)
+
+(binae lis-of-bin-lists) - same as above, but now we specify a list of
+byte-size - bin-list lists. For example assembling
+(binae ((2 (1 2)) (4 (3 4)))) results in (1 0 2 0 3 0 0 0 4 0 0 0)
+
(space size &optional (fill 0)) - pad assembly output with size amount of
bytes, all of value fill
-"string" - a literal string will be encoded as utf-8 transformed bytes, at
-arnesi's string-to-octets discretion and will be 0-terminated
-
-(string &rest strings) - strings will be concatenated and then encoded as utf-8
-transformed bytes, at arnesi's string-to-octets discretion. If the symbol
-:null-terminated is present, the concatenated (so NOT the individual) strings
-will be null-terminated.
+"string" - a literal string will be encoded as *string-encoding* (defaults to :utf-8)
+specified transformed bytes, at arnesi's string-to-octets discretion and will be
+*string-end* (defaults to 0) terminated
+
+(string &rest strings) - strings will be concatenated and then encoded as
+*string-encoding* (defaults to :utf-8) transformed bytes, at arnesi's
+string-to-octets discretion. If the symbol :null-terminated is present,
+the concatenated (so NOT the individual) strings will be null-terminated.
:label - an unadulterated keyword will be treated as a label
@@ -208,6 +236,7 @@
for if one wants to jump to code which might be placed directly after the compiled
code.
+
* pseudo-instructions
(ldr register literal) - loads the value of literal in register. Encodes in two's
@@ -231,9 +260,8 @@
Coprocessors can be written as px or cpx where x is a number from 0 to 15.
-** History
-This is version 0.1, aka the first one.
+** History
The core of the thing is a file called thumb.lisp, which Jeff Massung was so
kind to dig up from his digital archive. It was a beta version of a thumb
@@ -243,11 +271,11 @@
traditional assembler. Who knows, maybe you can even have some use for it.
+
** Todo
- no arm or thumb adrl pseudo-instruction
-- in the arm ldr instruction, encode a
-- constant load more efficiently if possible in stead of always loading from
-- memory write enhanced dsp instructions
-
+- in the arm ldr instruction, encode a constant load more efficiently if possible
+in stead of always loading from memory
+- write enhanced dsp instructions
- document code think about a comment-extractor
\ No newline at end of file