Browse code
Added documentation and automatic execution of assembled source
Andrew Alderwick authored on 15/05/2021 20:49:46
Showing 1 changed files
| ... | ... |
@@ -5,9 +5,54 @@ |
| 5 | 5 |
|
| 6 | 6 |
( vectors ) |
| 7 | 7 |
|
| 8 |
+( |
|
| 9 |
+ Asma - an in-Uxn assembler |
|
| 10 |
+ |
|
| 11 |
+ This assembler aims to be binary compatible with the output from |
|
| 12 |
+ src/assembler.c, but unlike that assembler this one can be run inside Uxn |
|
| 13 |
+ itself! |
|
| 14 |
+ |
|
| 15 |
+ Asma is designed to be able to be copy-pasted inside another project, so |
|
| 16 |
+ all its routines are prefixed with "asma-" to prevent clashes with labels |
|
| 17 |
+ used in the incorporating project. The reset vector contains a couple of |
|
| 18 |
+ examples of asma's usage and can be discarded. |
|
| 19 |
+) |
|
| 20 |
+ |
|
| 8 | 21 |
|0100 @reset |
| 22 |
+ ( |
|
| 23 |
+ Assemble the source code into an output ROM file. |
|
| 24 |
+ |
|
| 25 |
+ If all you want is to use asma.usm to assemble files, insert a BRK |
|
| 26 |
+ after this statement. |
|
| 27 |
+ ) |
|
| 9 | 28 |
;&source-file ;&dest-file ;asma-assemble-file JSR2 |
| 10 |
- BRK |
|
| 29 |
+ |
|
| 30 |
+ ( |
|
| 31 |
+ If an error has occurred, BRK here, otherwise continue. (The error |
|
| 32 |
+ message will already have been printed to the Console in |
|
| 33 |
+ asma-assemble-file.) |
|
| 34 |
+ ) |
|
| 35 |
+ ;asma/error LDA2 #0000 EQU2 JMP BRK |
|
| 36 |
+ |
|
| 37 |
+ ( |
|
| 38 |
+ Load the output ROM over the currently running program, almost as if |
|
| 39 |
+ we loaded the ROM with uxnemu directly! |
|
| 40 |
+ |
|
| 41 |
+ It's not a totally pristine environment, as File/load doesn't zero out |
|
| 42 |
+ memory beyond the end of the file. So if the assembled program assumes |
|
| 43 |
+ that all memory above it is zero, it may misbehave. |
|
| 44 |
+ |
|
| 45 |
+ Asma itself doesn't use the zero page, but this example code writes a |
|
| 46 |
+ DEO2 instruction to 0x00ff. In order to execute File/load and have the |
|
| 47 |
+ CPU continue at memory location 0x0100, we write the final DEO2 |
|
| 48 |
+ instruction there and jump there as our final act. |
|
| 49 |
+ ) |
|
| 50 |
+ ;&dest-file .File/name DEO2 |
|
| 51 |
+ #0000 .File/offset DEO2 |
|
| 52 |
+ #ff00 .File/length DEO2 |
|
| 53 |
+ #0100 .File/load |
|
| 54 |
+ LIT DEO2 #00ff STA |
|
| 55 |
+ #00ff JMP2 |
|
| 11 | 56 |
|
| 12 | 57 |
&source-file |
| 13 | 58 |
"projects/demos/piano.usm 00 |
| ... | ... |
@@ -21,13 +66,14 @@ |
| 21 | 66 |
%asma-IF-ERROR { ;asma/error LDA2 ORA }
|
| 22 | 67 |
%asma-LOG { #01 }
|
| 23 | 68 |
( |
| 24 |
- #00 first pass output |
|
| 25 |
- #01 second pass output |
|
| 26 |
- #02 current token |
|
| 27 |
- #04 label dump at end |
|
| 69 |
+ asma-LOG is a log-level parameter for helping to debug stuff. |
|
| 70 |
+ It's value is the bitwise OR of all the following output types: |
|
| 71 |
+ #01 prints the number of lines in the source code, |
|
| 72 |
+ #02 prints tokens as they are processed, and |
|
| 73 |
+ #04 dumps all defined labels at end. |
|
| 28 | 74 |
) |
| 29 |
-%asma-DEO2 { asma-LOG NEQ JMP DEO2k POP POP2 }
|
|
| 30 |
-%asma-DEO { asma-LOG NEQ JMP DEOk POP2 }
|
|
| 75 |
+%asma-DEO2 { asma-LOG AND #00 EQU JMP DEO2k POP POP2 }
|
|
| 76 |
+%asma-DEO { asma-LOG AND #00 EQU JMP DEOk POP2 }
|
|
| 31 | 77 |
|
| 32 | 78 |
( |
| 33 | 79 |
Asma's public interface. |
| ... | ... |
@@ -70,6 +116,7 @@ |
| 70 | 116 |
#20 .Console/char DEO |
| 71 | 117 |
;asma/orig-token LDA2 .Console/string DEO2 |
| 72 | 118 |
;&line .Console/string DEO2 |
| 119 |
+ ( FIXME it would be nicer if line numbers were in decimal ) |
|
| 73 | 120 |
;asma/line LDA2 .Console/short DEO2 |
| 74 | 121 |
#2e .Console/char DEO |
| 75 | 122 |
#0a .Console/char DEO |
| ... | ... |
@@ -78,8 +125,9 @@ |
| 78 | 125 |
&line 20 "on 20 "line 20 00 |
| 79 | 126 |
|
| 80 | 127 |
@asma-print-linecount ( -- ) |
| 81 |
- ;asma/line LDA2 .Console/short #04 asma-DEO2 |
|
| 82 |
- ;&lines .Console/string #04 asma-DEO2 |
|
| 128 |
+ ( FIXME it would be nicer if line numbers were in decimal ) |
|
| 129 |
+ ;asma/line LDA2 .Console/short #01 asma-DEO2 |
|
| 130 |
+ ;&lines .Console/string #01 asma-DEO2 |
|
| 83 | 131 |
JMP2r |
| 84 | 132 |
|
| 85 | 133 |
&lines [ 20 "lines 20 "in 20 "total. 0a 00 ] |