-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathREADME.txt
340 lines (251 loc) · 13.6 KB
/
README.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
======================================================================================
Aboloka-8 Reference Manual
Created by Avuxo
======================================================================================
Aboloka-8
The Aboloka-8 is a fantasy retro computer based off of old soviet
home computers. The system is inspired by projects like Pico-8.
Unlike with systems like the Pico-8 (a fantasy retro console), it
is not a game console, and is more reminiscent the ZX Spectrum.
The Aboloka-8 provides a custom instruction set specifically tai-
lored to make assembly programming fun and accesible to provide
an introduction to a generation of people who have never and pro-
bably will never write assembly code for their actual home compu-
ters.
At the github repository for Aboloka-8 there are two implementat-
ions of the specification defined in this manual and other liter-
ature regarding the Aboloka-8. There is an implentation in C usi-
ng SDL for graphics. The second implementation is written in JS
using Canvas for graphics. The github is visible at Avuxo's page
at https://github.com/avuxo/aboloka-8
:: Specifications
Display: 128x128 pixels, monochrome
Input: 30 key keyboard. 0-9, a-Z, shift, space, execute
Memory size: 64KB
Tape size: 54KB (can hold 2 tapes, both R/W)
Internal storage: 16KB
8-bit Registers: 4 (X,Y,Z,A -- X,Y,Z General; A accumulator)
:: Hello world!
Below is an example of how the standard hello world would look
in the instruction set used by Aboloka-8.
In order to get to the point where you can write this program,
type ed at the prompt. This will open up the standard Aboloka-8
editor. From here, enter insertion mode at line 0 by typing i 0.
PROGRAM hello
ld $0002, "Hello, world!" ; load "Hello world" into 0x02 in memory
ld $000B, #$00 ; load a null terminator into 0x0B in memory
PRINT $02 ; print whatever is between 0x02 and null term.
exit ; return to OS
Note: for more info on the instruction set, look at the "program-
ming" section later in this manual.
exit and save by hitting the ESC key and typing :wq hello.a
This will save the file as hello.a on the local 16kb internal
storage.
To create an executable program, type asm hello.a hello EXEC into
the propmt. This will assemble the program and produce an execu-
table program.
:: The OS
The Aboloka-8 comes with a built in operating system that is aut-
omatically loaded from the internal ROM. The operating system is
written in Aboloka-8 assembly and is replacable if you want a di-
fferent experience with the Aboloka.
The OS comes with a list of built in programs that can be execut-
ed to perform basic tasks.
ed the basic editor, a line based text editor
mv move files from x y
asm the assembler for all user programs
rm remove a file forever (overwrites with zeros)
ld load a tape (takes argument 0 or 1) see: tapes
mem print current memory usage
Programs can be run any time that there is a $ showing (indicati-
ng that the prompt is ready to be run).
Arguments are provided to programs by separating them by spaces.
ex: rm hello.a EXEC would delete the file hello.a
The OS does not support sub-directories. Everything is stored in
the root directory or on a tape.
If you ever need to restart the Aboloka-8, use the F1 key on you-
r computer. This will restart the computer and clear the RAM.
Before a restart, ensure that you have put any code that you wis-
h to backup up on a tape. Tapes will NOT be cleared at restart.
:: Tapes
The Aboloka-8 comes with two virtual tape drives. These tape drives
are interfaced with via the ld command.
When ld is run on a drive, it begins reading code at $00. Any prog-
gram there will be loaded.
Tapes contain 54kb of storage for writing and distributing tapes.
Tapes can be distributed from your host operating system using the
.tape file format.
:: Instruction set
The Aboloka-8 uses 8-bit opcodes that translate 1:1 with the mneu-
monic instruction set.
Any number prefixed with a $ is in hexadecimal. Any number prefix-
xed with a # is a literal value.
instruction op description length
==================== == ================================= ======
ld $ADDRESS, #$VALUE 10 load the hex VALUE into ADDRESS 4
ldx #$VALUE 11 load the hex value VALUE into X 2
ldy #$VALUE 12 load the hex value VALUE into Y 2
ldz #$VALUE 13 load the hex value VALUE into Z 2
lda #$VALUE 14 load the hex value VALUE into A 2
ldx $ADDRESS 15 load the value at an address into X 3
ldy $ADDRESS 16 load the value at an address into Y 3
ldz $ADDRESS 17 load the value at an address into Z 3
lda $ADDRESS 18 load the value at an address into A 3
cpx #$VALUE 1A compare the hex value VALUE with X 2
cpx $ADDRESS 1B compare X with the value at address 3
cpy #$VALUE 1C compare the hex value VALUE with Y 2
cpy $ADDRESS 1D compare Y with the value at address 3
cpz #$VALUE 1E compare the hex value VALUE with Z 2
cpz $ADDRESS 1F compare Z with the value at address 3
jmp $ADDRESS 20 jump to the memory location ADDRESS 3
jmp REG 21 jump to the register REG 2
je $ADDRESS 22 jump only if eq flag is set 3
jne $ADDRESS 23 jump only if eq flag is not set 3
call $ADDRESS 25 jump and push return addr to stack 3
ret 26 pop ret address off the stack and jump 1
add #$VALUE 30 add VALUE to A 2
adm $ADDRESS, #$VALUE 31 add VALUE to memory location ADDRESS 4
sub #$VALUE 32 subtract VALUE form A 2
sbm $ADDRESS, #$VALUE 33 sub VALUE from memory @ADDRESS 4
inc $ADDRESS 34 add 1 to whatever value is in ADDRESS 3
inc REG 35 add 1 to whatever is in the register 2
dec $ADDRESS 36 subtract one from ADDRESS' value 3
dec REG 37 subtract one from whatever is in REG 2
clf 40 clear all status flags 1
emit #$VALUE 55 echo a single ascii character 2
emit REG 46 echo a single character in a register 2
print $ADDRESS 57 print at ADDRESS until a 0x00 is found 3
nop E9 do nothing 1
exit EA exit the program 1
:: Opcodes
The Aboloka-8 uses 32 bit fixed-width instructions separated into 4
bytes. However, not all instructions use all 32 bits, all unused
bits are simply zeroed out in this case. The below diagram explains
the bit pattern of opcodes.
[opcode: 8 bits][operands: 24 bits]
[arg1] [arg2] [arg3]
01 23 45 67
| | | |
| | | +----- Operand byte 3
| | +-------- Operand byte 2
| +----------- Operand byte 1
+-------------- The opcode (the operation)
For example: the assembly instruction
ld $0040, #$30
would translate to the bit pattern
10 00 40 30
| | | |
| | | +----- The byte being written to the address (arg2)
| | +-------- The second byte of 0x040 (the address) (arg1)
| +----------- The first byte of 0x0040 (the address) (arg1)
+-------------- The ld instruction
For an example of an instruction that doesn't use all 4 bytes:
clf
Would translate to
40 00 00 00
In machine code, only utilizing the opcode. The rest of the
instruction is irrelevant because clf takes 0 arguments
:: Subroutines
Subroutines are created using the label syntax seen in other diale-
cts of assembly. Although in machine code the opcode jumps to a lo-
cation in the program, when actually programming, you can use simp-
le to use names.
; subroutine to add 2 numbers
; add (int a, in b) -> (int c)
subroutine add:
add X ; add A to X
ret ; jump back to call location
ldX $3B ; load 0x3B into X
ldA $6 ; load 0x06 into A
call add ; call the add subroutine
emit A ; print out the char 'A'
When creating a subroutine, the 'call' and 'ret' instructions are
used. call pushes the return address onto the stack and jumps to
the subroutine, and ret returns to the location pushed to the st-
ack. Due to direct memory access being possible, the stack is re-
ally only used as a call stack. This call stack is only 500 bytes
wide, so deep recursion is not advised.
The call stack goes from $1001-$11f5, if the subroutine attempts
to push an address any further than that, it will raise a stack
overflow exception.
:: Labels
An alternative to the subroutine mechanism is the ability to
create human-readable labels to jump to. Using this mechani-
sm, it is easy to create loops or branching paths.
Below is an example showing both loops and branching paths using
only the jmp and cpa instructions.
The example also shows off a (non-required) function of labels:
they can be used inside of subroutines. They can also be
used outside of subroutines, but it's better to show that
they can be used inside.
subroutine test:
lda #$41
jmp repeat
label repeat:
cpa #$51
je done
emit A
inc A
jmp repeat
label done:
exit
It should be noted however that labels are NOT scoped meaning
that jumping to a label inside of another subroutine could lead
to an issue. Just bear this in mind while using labels as it is
the major limitation relating to them.
In terms of naming conventions, labels should probably be named
as follows:
SUBNAME_ACTION
The above example's labels would be better named as:
repeat -> test_repeat
done -> test_done
As to fit within these naming conventions. They were named as
shown simply for readability reasons (and there can't be scop-
ing issues in a code snippet).
:: Memory Layout
In the Aboloka-8 there are a number of important memory regions.
The system has no memory safety, which means that any program can
write anywhere in memory.
$0000-$1000 ROM for programs and OS
$1001-$11f5 call stack
$1001-$3FFF free memory for user use.
$4000-$8000 graphics memory (each byte is 1 pixel).
$3000-$30FF keyboard input memory.
$30FF-$FA00 free memory for user use.
:: CPU Status Flags
The Aboloka-8's CPU features an unsigned 8-bit integer holding all
of the system's flags.
The bits are arranged as follows:
A B C D E F G H
| | | | | | | |
| | | | | | | +- eq flag, when a cmp returns true
| | | | | | +--- carry flag, on unsigned arithmetic with carry
| | | | | +----- overflow flag, used in signed arithmetic
| | | | +------- none (currently unused)
| | | +----------- none (currently unused)
| | +------------- none (currently unused)
| +--------------- none (currently unused)
+----------------- none (currently unused)
:: Graphics programming
In order to write to a specific pixel, an 8-bit color value is writ-
ten to a specific area in memory. Whatever value is in that byte wi-
ll be drawn to the screen when it comes time for the screen to be r-
efreshed.
The graphics block of memory starts at $4000 and goes to $8000. Any
8-bit color value can be drawn here. if a byte is $00 then it will
be drawn as black. In order to clear the screen, the memory should
simply be zeroed out.
The following code snippet will draw a white box in the top left of
the screen (exit the program by restarting as you will be in an in-
finite loop).
PROGRAM box
label draw:
ld $4000, #$01
ld $4001, #$01
ld $4081, #$01
ld $4082, #$01
jmp draw
The above code functions because it loads the value $01 (white) into
the block of memory used to draw graphics. The code constantly jumps
to the start to make sure that it continues drawing and never exits.
As such, the code cannot be exited without a full system restart.