changed readme to report about escaping emit-asm
Annotate for file /README
2007-11-03 ties 1
21:39:17 ' 2
' 3 *** Armish - An assembler quite contraire
2007-03-09 Ties 4
22:55:04 ' 5 Armish is the Amish of the computer-world. The Amish plough forth through life
' 6 under the twin burden of an extreme religion and an accompanying extreme way of
' 7 life. As a result they're marginalized and they watch life pass them by. But
' 8 they might just hold the seed for a future way of living, you know, with global
' 9 warming and all. It has worked in the past; You never know. You never know I
' 10 say.
' 11
' 12 Armish ploughs through bit-space under the twin burden of being an assembler
' 13 and being written in lisp. As a result it will be marginalized and it will
' 14 watch with an unending waxing headache how programmers pass it by, riding their
' 15 high octane steeds of high-level languages. But it might just hold the seed for
' 16 a future mass acceptance of languages long forgotten, garbage collected os-ses
' 17 of yonder, recursive programming-joys untold... (*sigh*) ... You never
' 18 know... You never know, da#@^$it!!
' 19
' 20
2007-11-03 ties 21
2007-03-09 Ties 22 ** License - LLGPL, see the LICENSE file
22:55:04 ' 23
' 24 ** Authors
' 25
' 26 - Jeff Massung
' 27 - Ties Stuij
' 28
' 29
2007-11-03 ties 30
2007-03-09 Ties 31 ** Concept
22:55:04 ' 32
2007-11-03 ties 33 Armish is an assembler like any other. With parenthesis around the instructions.
21:39:17 ' 34 It's Armish's aim is to be a bit on the general side. It assembles arm and thumb
' 35 code, but new features of the latest processors are not (yet/ever) supported.
' 36 They're quite backwards compatible though, those processors, last time I checked.
' 37 Armish should be usable for arm architectures 3 through 5 (till arm9), and of those
' 38 just the core. No enhanced dsp instructions or such. Complaints about missing
' 39 features are welcome. See Liards, for a lib that actually uses it.
2007-03-09 Ties 40
22:55:04 ' 41
' 42
' 43 ** Installation
' 44
' 45 To get the latest development version, do a darcs get:
' 46
' 47 darcs get http://common-lisp.net/project/armish/darcs/armish
' 48
2007-11-04 ties 49 Versioned releases have been put to a halt atm.
09:15:01 ' 50
' 51 Armish depends on Umpa-Lumpa, Arnesi, Split-Sequence and FiveAM.
' 52
' 53 darcs get http://common-lisp.net/project/liards/darcs/umpa-lumpa
' 54 darcs get http://common-lisp.net/project/bese/repos/arnesi_dev
' 55 darcs get http://common-lisp.net/project/bese/repos/fiveam
' 56 http://ww.telent.net/cclan/split-sequence.tar.gz
2007-03-09 Ties 57
2007-11-04 ties 58 Once you've got those wired into your asdf machinery together with Armish,
09:15:01 ' 59 just fire it up.
2007-03-09 Ties 60
2007-11-03 ties 61
2007-03-09 Ties 62 ** Testing
22:55:04 ' 63
' 64 You can check if (a subset of) all the standard instructions work by first
' 65 building aasm from the supplied c source if you're not on linux or windows, and
' 66 be sure to name it aasm. For linux the executable is already there. Make the
' 67 executable executable (`chmod 755 aasm' or equivalent) and then execute: (run!
' 68 'arm-suite)
' 69
' 70 There might by errors here caused by the fact i faultily tried to support your
' 71 implementation or operating system. The test tries to access an external
' 72 assembler supplied with Armish to test the instructions; however the functions
' 73 to read and write to other processes is implementation-dependent. Armish is
' 74 only tested on sbcl on Linux, so if you can, please fix by editing run-prog and
' 75 process-output in helpers.lisp and control-check in test.lisp. Oh! and send a
' 76 fix if you want! Thanks. Or just remove your implementation from the two
' 77 feature-query lists in control-check.
' 78
' 79 This will compare the output of Armish with that of a reference implementation,
' 80 included in this release. This shouldn't be to interesting for the average
' 81 user. I would myself at least expect the tested functionality to work. It might
' 82 give you a warm fuzzy feeling to know this assembler doesn't just fool you
' 83 along, like it would me. More interesting is perhaps that you can check the
' 84 syntax of this assembler by looking at the test-cases in the test.lisp file.
' 85
' 86 More practical for if you do feel the need to hack on this assembler-thing (i
' 87 for one encourage it) is that you'll find some handy functions in the test.lisp
' 88 file that can help with debugging.
' 89
' 90
2007-11-03 ties 91
2007-03-09 Ties 92 ** Exported functions
22:55:04 ' 93
' 94 - assemble - Assembles forms into a list of opcodes for specified chip and
2007-10-21 ties 95 processor mode. syntax: (assemble chip mode forms) where:
2007-03-09 Ties 96
22:55:04 ' 97 chip - decides which chipset to assemble for - is a number or a symbol
' 98
' 99 Atm assemble accepts the first value of the pairings below, and it translates
' 100 into the latter. The higher the value, the newer the chip. Check the function
' 101 get-version to see the latest supported symbols or to add your own.
' 102
' 103 0 0 'all 0 3 3 4 4 'version-4 4 '4t 4.2 'ARM7TDMI 4.2 'arm7 4.2 5 5 'version-5
' 104 5 '5TExP 5.3 '5TE 5.4 'ARM946E-S 5.4 'arm9 5.4
' 105
' 106
' 107 mode - decides if you want to start in arm or thumb mode - accepts one of the
' 108 following symbols: 'arm 'code32 'thumb 'code16
' 109
' 110
' 111 forms - are, yes, the forms to be assembled
' 112
2007-10-21 ties 113 example usage:
15:40:14 ' 114 (assemble 'arm9 'arm
2007-10-21 ties 115 '(:label (mov r3 r4) (b :label)))
2007-10-21 ties 116
15:40:14 ' 117 ==> (4 48 160 225 253 255 255 234)
2007-03-09 Ties 118
2007-10-21 ties 119
17:01:29 ' 120 - emit-asm - emits a list of assembly forms ready to be fed to assemble. Emit-asm
' 121 escapes variables which are not part of the assembler syntax, so we can enrich the
2007-11-04 ties 122 assembler with variables, while still keeping a clean, uniform syntax. Inside
09:58:52 ' 123 emit-asm, escape forms you want to evaluate as Common Lisp with (ea ...), as in
' 124 escape assembler.
2007-10-21 ties 125
17:01:29 ' 126 syntax: (emit-asm form1 form2 ...)
' 127
' 128 example usage:
' 129
' 130 (let ((foo 'r4)
' 131 (bar 'r6))
' 132 (emit-asm
' 133 :loop
' 134 (stmib r3 (r3 foo_bar))
' 135 (b :loop)))
' 136
' 137 ==> (:LOOP (STMIB R3 (R3 R4_R6)) (B :LOOP))
' 138
' 139
2007-03-09 Ties 140 - align - aligns a list of bytes to a bytes byte boundry by padding
2007-10-21 ties 141 zeroes. Defaults to four if bytes is not supplied
17:01:29 ' 142
' 143 syntax: (align byte-lst &optional bytes)
2007-03-09 Ties 144
22:55:04 ' 145 example usage: (align '(1 2 3 4 5)) ==> (1 2 3 4 5 0 0 0)
' 146
' 147
' 148 - aligned - returns the next bytes byte aligned address. Defaults to four if
2007-11-03 ties 149 bytes is not supplied
21:39:17 ' 150
' 151 syntax: (aligned address &optional bytes)
2007-03-09 Ties 152
22:55:04 ' 153 example usage: (aligned (length '(1 2 3 4 5))) ==> 8
' 154
' 155 There are some other functions exported (actually just one at the time of
' 156 writing), but those are simple helper functions that might aid the programmer
' 157 on a general level. I had a seperate package for that, but decided to cut it to
' 158 keep the package-count down. But i might reintroduce it again. Look in
' 159 helpers.lisp for functions that might aid you.
' 160
' 161
2007-11-03 ties 162 - set-armish-string-encoding - sets the armish string encoding. Armish passes
21:39:17 ' 163 the encoding to the arnesi string-to-octets fuction, which tries to do the right
' 164 thing. From the documentation: "We gurantee that :UTF-8, :UTF-16 and :ISO-8859-1 will
' 165 work as expected. Any other values are simply passed to the underlying lisp's
' 166 function and the results are implementation dependant.
' 167
' 168 syntax: (set-armish-string-encoding :keyword)
' 169
' 170 example usage: (set-armish-string-encoding :ISO-8859-1) ==> :ISO-8859-1
' 171
' 172
' 173
2007-03-09 Ties 174 ** Instruction syntax
22:55:04 ' 175
' 176 Basically this assembler follows the arm assembler syntax but then lispified:
' 177 Wrap the expressions in parenthesis, get rid of the comma's, substitute curly
2007-10-20 ties 178 braces and braces for parenthesis, substitute - for _ in register lists for
10:03:33 ' 179 multiple load/store instructions and get rid of the pound signs before
2007-03-09 Ties 180 literals and immediates. Barrel rolling modifiers and labels are keywords.
22:55:04 ' 181
2007-10-20 ties 182 examples:
10:03:33 ' 183 standard assembly syntax lisp syntax
2007-03-09 Ties 184
2007-10-20 ties 185 ldmhied r12!, {r2, r15, r13-r14} -> (ldmhied r12! (r2 r15 r13_r14))
10:03:33 ' 186 ldrbt r5, [r2], -r1 ror #12 -> (ldrbt r5 (r2) -r1 :ror 12)
2007-03-09 Ties 187
22:55:04 ' 188 For a pretty extensive, case by case comparison of the instructions, see the
' 189 test cases in the test.lisp file.
' 190
' 191
2007-11-03 ties 192
2007-03-09 Ties 193 ** Assembler format, features and conventions
22:55:04 ' 194
2007-11-03 ties 195
2007-03-09 Ties 196 * Directives
22:55:04 ' 197
' 198 code16 - assemble as thumb code32 - assemble as arm
' 199
' 200 pool - dump the literary pool
' 201
' 202 align - align code to a 4 byte boundary align-hw - align code to a 2 byte
' 203 boundary (align &optional bytes) - aligns code to a bytes byte boundary;
' 204 defaults to four if bytes is not supplied
' 205
' 206 (dcb byte &rest bytes) - define one or more bytes (byte byte &rest bytes) -
' 207 same as dcb
' 208
' 209 (dcw byte &rest bytes) - define one or more 16 bit words (hword byte &rest
' 210 bytes) - same as dcw
' 211
' 212 (dcd byte &rest bytes) - define one or more 32 bit words (word byte &rest
' 213 bytes) - same asl dcd
' 214
' 215 (dword byte &rest bytes) - define one or more 64 bit words (quad byte &rest
' 216 bytes) -define one or more 64 bit words
' 217
2007-11-03 ties 218 (bin byte-size bin-list) - a more general directive than the previous ones.
21:39:17 ' 219 First specify how many bytes of storage space the data items of the bin-list
' 220 should take, then supply the list itself. For example assembling
' 221 (bin 2 (1 2 3 4)) results in (1 0 2 0 3 0 4 0)
' 222
' 223 (binae lis-of-bin-lists) - same as above, but now we specify a list of
' 224 byte-size - bin-list lists. For example assembling
' 225 (binae ((2 (1 2)) (4 (3 4)))) results in (1 0 2 0 3 0 0 0 4 0 0 0)
' 226
2007-03-09 Ties 227 (space size &optional (fill 0)) - pad assembly output with size amount of
22:55:04 ' 228 bytes, all of value fill
' 229
2007-11-03 ties 230 "string" - a literal string will be encoded as *string-encoding* (defaults to :utf-8)
21:39:17 ' 231 specified transformed bytes, at arnesi's string-to-octets discretion and will be
' 232 *string-end* (defaults to 0) terminated
2007-03-09 Ties 233
2007-11-03 ties 234 (string &rest strings) - strings will be concatenated and then encoded as
21:39:17 ' 235 *string-encoding* (defaults to :utf-8) transformed bytes, at arnesi's
' 236 string-to-octets discretion. If the symbol :null-terminated is present,
' 237 the concatenated (so NOT the individual) strings will be null-terminated.
2007-03-09 Ties 238
22:55:04 ' 239 :label - an unadulterated keyword will be treated as a label
2007-10-27 ties 240
19:24:12 ' 241 For convenience the to be compiled forms are appended with the :code-end label,
' 242 for if one wants to jump to code which might be placed directly after the compiled
' 243 code.
2007-03-09 Ties 244
2007-11-03 ties 245
2007-03-09 Ties 246 * pseudo-instructions
22:55:04 ' 247
2007-10-24 ties 248 (ldr register literal) - loads the value of literal in register. Encodes in two's
21:16:04 ' 249 complement
' 250 (ldr register literal :pi) - loads the value of literal in register, as Positive
' 251 Integer, understand (or 0)
' 252
' 253 (adr register label) - loads the address of label in register
' 254 (nop) - no opcode; translates into (mov r0 r0) in arm and
' 255 (mov r8 r8) in thumb
2007-03-09 Ties 256
22:55:04 ' 257
' 258 * register and coprocessor syntax
' 259
' 260 Registers can be written in the familiar way: rx, where x is a number from 0 to
' 261 15. the lr, sp, and pc can be written like lr, sp and pc.
' 262
' 263 Coprocessor registers can be written as cx or crx where x is a number from 0 to
' 264 15.
' 265
' 266 Coprocessors can be written as px or cpx where x is a number from 0 to 15.
' 267
' 268
' 269
2007-11-03 ties 270 ** History
2007-03-09 Ties 271
22:55:04 ' 272 The core of the thing is a file called thumb.lisp, which Jeff Massung was so
' 273 kind to dig up from his digital archive. It was a beta version of a thumb
' 274 assembler and it assembled thumb opcodes if you fed it instructions. It has
' 275 been expanded upon a bit by the Armish team of one by modifying the thumb code
' 276 a bit and by adding arm instructions and facilities to make it more like a
' 277 traditional assembler. Who knows, maybe you can even have some use for it.
' 278
' 279
2007-11-03 ties 280
2007-03-09 Ties 281 ** Todo
22:55:04 ' 282
2007-10-20 ties 283 - no arm or thumb adrl pseudo-instruction
2007-11-03 ties 284 - in the arm ldr instruction, encode a constant load more efficiently if possible
21:39:17 ' 285 in stead of always loading from memory
' 286 - write enhanced dsp instructions
2007-03-09 Ties 287 - document code think about a comment-extractor