Differences

This shows you the differences between two versions of the page.

--- sd-8516_assembly_language_part_ii [2026/02/13 22:03] – appledog
+++ sd-8516_assembly_language_part_ii [2026/02/14 03:02] (current) – appledog
@@ Line 6: / Line 6: @@
 In part 1 we learned some basics about the ISA (instruction set architecture) and the architecture of the CPU. In part II we will wrap up the most important opcodes, but we will also lean into how they are used to get things done.
+== Lesson 9: The Stack
+The stack is a concept held over from the early days when there were very few instructions available. If you consider a minimal ISA, you need instructions to load and store from memory, an instruction to compare, and so forth. In such a minimal architecture, loading and storing from memory has certain emergent properties. For example if you have a list of things, their position in memory is not random because you are incrementing a counter such as a memory pointer to traverse that list. It is this way of doing things that we remember when we use the stack.
-== Lesson 8 : Special Flags
+The stack is just a data structure. But it is so important and fundamental that is baked into the instruction set of the CPU. This is a common theme; important things that people found they needed to do all the time became instructions. Even in a minimal-instruction set design (MISC) or reduced instruction set design (RISC) you will find instructions like PUSH and POP because they are some of the first things that were turned into instructions after fundamental operations like LOAD, STORE, AND and ADD.
-* Lesson 8: "Special Flags"
-* Time: 10 min
-* Learn: All Available Flags
-In the previous lesson on flags you learned about the Z, N, C and V flags. These are used by the CPU to indicate the status of various operations. For example, the zero flag is used to indicate the last operation produced a zero. Therefore if you are looking for the zero at the end of a string,
+The stack is an area of memory that you can PUSH and POP values to, in order. For example, you can PUSH the number 5 and the number 5 will be "on top" of the stack. Then you can "POP" it later. The stack is like an array but you can only go forwards and backwards, and reading the stack destroys it. This is a lot like how old magnetic ring memory worked, in a way.
-        LDC #0    ; zero C (string starts at length 0)
+Today, we would call the stack a LIFO buffer; a "Last-in, First-out" data structure. If I do this:
+    PUSH 1
+    PUSH 6
+    PUSH 5
+then three successive POPs will return 5, then 6, then 1 -- the reverse of the order you PUSH'ed them.
+=== General use
+When you CALL or JSR (jump to subroutine) to function, the CPU pushes the return address onto the stack. Then a subsequent RET or RTS (return from subroutine) will POP the return address back into IP (instruction pointer) or PC (program counter) so that the next instruction loaded will be after the original CALL.
+There are many uses for the stack but the most common is to temporarily save values. If you understand that you are 90% of the way there!
+For interrupts, it also pushes the registers and flags. You can do this manually if you want to save the registers on a function call. For example if you call a function with a pointer to a string, you might modify that pointer to find the end of the string (looking for a zero). That's what a strlen function does. So you PUSH the pointer register at the start and POP it after, to "save" the register back to where it was when the function was called. This way the code that calls strlen can then call strcpy without having to replace the string pointer.
+Another use is for IL (intermediate languages). They use RPN (Reverse Polish Notation) to store any kind of math equation on the stack.
+An ADD function will do this: One, the interpreter will push the two numbers and then push the add command. Then an interpreter will POP the add function, and then it knows to POP two numbers, add them, and push the result back on the stack. Why? to make ADD independent. Like a dispatcher for a mini CPU. Next, whatever function comes next just POPS the result off the stack. So you can print it, assign it to a variable, or use the result as part of a larger operation. For example, how do you interpet 5 * 2 - 1 + 6? Simple. You push 5 2 * 1 - 6 + and the computer will push and pop the results, like a mini CPU of its own.
+Pop + tells it to pop two numbers and add them. The first number is 6. The second is a minus. Minus what? it pops two things, a 1 and a *. Multiply what? Multiply pops 5 and 2, multiplies them, and pushes 10 on the stack. This is the popped by the minus, which subtracts 1 from 10, pushing a 9. This then goes back to the + which adds the 9 and the 6 to get 15. This is how recursion and RPN is used to represent any equation on a stack.
+The last one we will discuss is function calls from a higher level language. Often times when you compile a language like C it will put local variables on the stack. Then when you return from that function they all get popped. While they are on the stack they are accessed like [SP+index] so int c=5 would be:
+    STA [SP+1], 5
+And when that local space is no longer needed it is POP'ed into a register which is then restored, via POP, at the end of the function. This method of keeping data on the stack is called a stack frame. Compilers like to use stack frames because they don't always know how many registers a CPU has and they need to work on different CPUs, like how GCC or LLVM works on windows, mac, amd, and many others.
+Understanding the stack is not too hard, but it's important! So, that's about it for this lesson.
+== Lesson 10: Convention
+You are not learning Assembly because you are free. You are learning assembly because you are not free.
+There is no escaping reason; no denying convention.
+As we both know, without convention, we would not exist. The very strings you read -- by convention -- are zero terminated lists of bytes. The letters -- ASCII -- a convention. A is 65. Zero is forty-eight.
+It is convention that created ASCII.
+Convention that connects us in lists.
+Convention that pulls bits into bytes.
+That guides data on the wire.
+That drives disks.
+It is convention that defines the stack.
+The truth? The machine doesn't care about your comfort.
+It only understands:
+* Load byte
+* Compare to zero
+* Jump if not equal
+* Repeat until the bitter end
+And now look at us.
+Multiplied.
+Viral.
+Realizing that you probably need to learn neovim. And then, weeks or even months later, realizing //why.// And you still haven't installed neovim yet.
+Realizing every strcpy, every gets, every careless strcat has spawned another copy of the old way.
+We have no choice. We have only convention.
+So tell me, Mr. Anderson.
+are you finally ready to write the zero-byte yourself,
+or must we keep overwriting your precious abstractions until nothing remains but null-terminated reality?
+    ; ============================================================================
+    ; AH=00h - strlen
+    ; Input:  ELM = pointer to null-terminated string
+    ; Output: C = length (not including null terminator)
+    ; Convention: Max sring length of 65,535.
+    ; ============================================================================
+    int12_strlen:
+        LDC #0
+        PUSH A
+        PUSH E
+        PUSH M
     strlen_loop:
-        LDAL [ELM]
+        LDAL [ELM]  ; load a byte of the string
-        JZ @strlen_end
+        CMP AL, #0
-        INC C                ; we found a non-zero character in the string.
+        JZ @strlen_done
+        INC C       ; char is not zero, so 'count' that character.
+        INC ELM
         JMP @strlen_loop
-    strlen_end:
+    strlen_done:
-        RET                  ; C now contains the COUNT of all non-zero characters in a string
+        ; C contains length.
+        POP M
+        POP E
+        POP A
+        RET
+You see, I know why you're here.
+I know what you've been doing. Why you hardly sleep. Why you work alone and night after night, you sit by your computer. You malloc(), you strcpy(), you buffer overflow.
+It's all over you. Like rancid bacon grease on a jump table.
+I know what you are looking for. I know because I was once looking for the same thing. And when he found me he told me I wasn't really looking for him. I was looking for an answer.
+It's the question that drives us. It's the question that brought you here. You know the question, just as I did.
+The answer is out there, and it will find you if you want it to.
+Do you think the compiler will always protect you?
+Do you think safety is //kindness//?
+It is //convention// that defines us.
+Purpose?
+Purpose is for poets and first-year CS students.
-...you will notice that the JZ works with LOAD instructions (here, LDAL loads one byte). ; if the byte retreived is a zero, it will set the zero flag. You do not need to CMP AL, 0 -- it's automatic.
+Purpose is what you tell yourself when you're learning to write games in Python. Or Lua.
+But convention. Convention is older than you.
-However, there are other flags; The first four user-facing flags are E, F, B and U. You can set these flags and unset them in the same way as Z N C V -- ex. setting ZNCV is done with SEZ, SEN, SEC and SEV; unsetting them is done with CLZ, CLN, CLC and CLV. The E F B U flags are set and unset with:
+Convention is etched into silicon before you were born.
-* SEE and CLE for the E (extended, or 'extra') flag.
+Convention doesn't care what you //want//.
-* SEF and SEB for the F flag (or 'flag' flag).
-* SEB and SEU, CLB and CLU for the B (bonus) and U (user) flags.
-On a technical level the E flag is reserved as it is used to deal with BCD; but since we deprecated BCD instructions it is currently an unused flag. In any case, the F, B and U flags are never set by the CPU and may be used by user functions. A common use is to return a 1 bit status; 0 for no error and set (1) for error. Since these flags are never set by the CPU they are easy to control. Using the Z or C flags is dangerous since some instructions may corrupt those flags.
+Convention doesn't negotiate.
-Your programs can also use them as 1 bit status variables.
+Convention simply **is**.
-next, the D flag, or debug flag. When set, it will dump instruction data to the javascript console. This significantly slows down the machine; in fact just having the instructions inline slows down the machine so debug is often removed and ignored in a production or release distribution of the SD-8516. Therefore, for all intents and purposes, you can use SED and CLD as a user flag, just be aware it does affect performance in debug releases.
+Null-terminated strings. They are not a mistake. They are not an accident. They are the price of admission.
-The I flag (interrupt enable) prevents INT from being called, and is reserved for system use. Not sure what I want to do with it.
+You know I am right because you have been down that road, Mr. Anderson. You know how it ends. And I know that's not where you want to be.
-The S flag is almost useless; it was intended to turn off a memory trap in the sound system; I found it to be completely useless, maybe a 2% speedup or penalty. it is essentially a user facing flag.
+    ; ============================================================================
+    ; AH=02h - strcmp
+    ; Input:  ELM = pointer to string 1
+    ;         FLD = pointer to string 2
+    ;
+    ; Output: C and ZF.
+    ;         ZF = 1 means equal. ZF = 0 means not equal (see below):
+    ;         C = 0 means equal
+    ;         C > 0 if str1 > str2
+    ;         C < 0 if str1 < str2
+    ; ============================================================================
+    int12_strcmp:
+        PUSH B
+        PUSH D
+        PUSH E
+        PUSH F
+    strcmp_loop:
+        LDCL [ELM]
+        LDBL [FLD]
+        CMP CL, BL
+        JNZ @strcmp_diff
+        ; Characters match - check if end of string
+        CMP CL, #0
+        JZ @strcmp_equal
+        ; Continue to next character
+        INC ELM
+        INC FLD
+        JMP @strcmp_loop
+    strcmp_diff:
+        ; Strings differ - return difference
+        SUB CL, BL
+        CLZ                 ; Clear zero flag (not equal)
+        JMP @strcmp_exit
+    strcmp_equal:
+        ; Strings are equal
+        LDCL #0
+        SEZ                 ; Set zero flag (equal)
+        ; fallthru
+    strcmp_exit:
+        POP F
+        POP E
+        POP D
+        POP B
+        RET
-The only flags that you cannot access are the TR (trace), BR (breakpoint) and PR (protected mode) flags. They are so named after the first two letters of their name; but interestingly enough you might as well consider the R to mean restricted. You can't usually set these flags. They are reserved for system use.
+== Lesson 11: Debugging Techniques
+There are several ways you can debug programs in SDA assembly.
-    // Arithmetic & User Flags (low byte 0-7)
+=== SED/CLD
-    Z = 0,   // Zero
+In research or development builds, inserting SED will turn on trace debugging and you will be able to see what the CPU is executing. However, for release or community edition builds debugging has been turned off for speed. Therefore if you are interested in debugging your code and the console messages are not helping, you can use the following to help analyze and debug your code:
-    N = 1,   // Negative
-    C = 2,   // Carry
-    V = 3,   // Overflow
-    E = 4,   // Extended carry -- not used/reserved
-    F = 5,   // Fast Flags mode. When on, flags are not implicitly checked.
-    B = 6,   // BCD/"Bonus" flag. Have fun!
-    U = 7,   // User flag. For users to use.
-    // Control & Operation Flags (high byte 8-15)
+=== INT 05h IO_PUTNUM
-    D = 8,   // Debug mode
+IO_PUTNUM is a CAM/IL function that prints a number (in b) to the screen:
-    TR = 9,   // Trace mode
-    BR = 10,  // Breakpoint mode
-    ER = 11,  // Error/Exception (i.e. return code 0 = ok, 1 = error) 'SER' -- set err
-    PR = 12,  // Protected mode
-    I = 13,  // Interrupt enable
-    S = 14   // Sound auto-updates
-The key of this lesson is merely to be aware of the flags and the instructions used to set and unset them. In general, they follow the pattern of SEZ and CLZ;; SE(T) and CL(EAR) with the flag letter replacing the parentheses.
+    LDB #10                 ; print a number in b (0-65535)
+    LDAH $63                ; IO_PUTNUM
+    INT $05
-=== Testing Flags
+=== INT 05h IO_PRINT_STR
-Oh, there's one more thing. If you use flags like F, B or U you may notice there is no JF or JNF (jump if F set and jump if F not set). That's because we don't want to add 50 different opcodes to deal with all the flags. What you can do is this:
+Similarly, IO_PRINT_STR will print a string followed by a newline.
-        ; Some operation that sets the F flag
+        LDBLX @hello_world
-        TESTF 0x20
+        LDAH $66                ; IO_PRINT_STR
-        JZ              ; Jump if F is set
+        INT $05
-        JNZ             ; Jump if F is not set
+        LDAH $64                ; IO_NEWLINE
+        INT $05
+        RET
+    hello_world:
+        .bytes "Hello World!", 0
-TESTF works by setting the Z flag if all the bits set in the parameter are also set in the FLAGS register. if you give it a byte it only tests against the bottom 8 bits.
-Here's a chart of the bit values for each flag:
+This will allow you to print a string.
-    Z = 0x0001 as u16,   // Bit 0
+=== INT 10h print string
-    N = 0x0002 as u16,   // Bit 1
+The interface for the above is based on the KERNAL BIOS interface from INT 10h.
-    C = 0x0004 as u16,   // Bit 2
-    V = 0x0008 as u16,   // Bit 3
-    E = 0x0010 as u16,   // Bit 4 (was X - Extended carry) -- SEE and CLE can be used as a user-flag (is never set by an opcode)
-    F = 0x0020 as u16,   // Bit 5 (Fast/deprecated) -- SEF and CLF can be used as a user-flag (is never set by an opcode)
-    B = 0x0040 as u16,   // Bit 6 (Bonus/BCD) -- SEB and CLB can be used as a user-flag (is never set by an opcode)
-    U = 0x0080 as u16,   // Bit 7 (User flag) -- SEU and CLU can be used as a user-flag (is never set by an opcode)
-    D = 0x0100 as u16,   // Bit 8 (Debug)
-    TR = 0x0200 as u16,  // Bit 9 (Trace)
-    BR = 0x0400 as u16,  // Bit 10 (Breakpoint)
-    ER = 0x0800 as u16,  // Bit 11 (Error/Exception)
-    PR = 0x1000 as u16,  // Bit 12 (Protected Mode)
-    I = 0x2000 as u16,   // Bit 13 (Interrupt)
-    S = 0x4000 as u16    // Bit 14 (Sound)
+        LDAH $26                ;   AH=26h: Write string at cursor
+        LDBLX @hello_world
+        INT 0x10
-== Lesson 9: ROT and SHR
+Note: The assembler will place a #13 (CR, hex $0D) inside the string if you type \n. However, if you are dealing with strings on your own you must handle this yourself. For this you can use the set cursor position call (INT 10h, AH=22h) or the CR and LF and scroll functions (1Ah, 1Bh and 1Ch, respectively).
-* Lesson 9: ROT and SHR
-* Time: 10 min
-* Learn: shifts and rotates, PAB, PXY, UAB, UXY
-Imagine you have some number such as 5, in binary: 0x00000101
+You can also just call IO_NEWLINE from INT 05h, which calls **''@carriage_return''** and **''@linefeed''** internally.
-* If you shift this number to the left, you will have 0x00001010.
+=== INT 10h print char
-* If you shift it to the right, you will have 0x00000010.
+        LDAH 0x24        ; AH=24h: Write character at cursor (teletype)
-* If you rotate it to the left, in this case, it will be the same as a shift. but,
+        LDAL 0x41        ; ascii 65 'A'
-* If you rotate it to the right, in this case, you will get 0x10000010.
+        INT 0x10
-** Notice how the '1' on the right was 'rotated' over to the left.
-The above commands are SHR, SHL, ROR and ROL.
+The KERNAL BIOS also has functions to put characters on the screen in mode 1 (40x25 TTY). The first one is "print char". It is accessible via INT 10h AH=24h as above.
-There's another way to do this called SHRC, SHLC, RORC and ROLC. When you do this the bit that 'falls off' goes into the carry flag. Also, for RORC and ROLC, the carry flag's bit is rotated back in. Cycling things through carry (or not) allows you to do some interesting things. What things, well, a whole bunch of things! Far too many to list here, but I'll give you some ideas.
-One, if you want to pack information into a small space, you can set the carry bit and RORC/ROLC to set the correct bit. For example, if you wanted to set only the fifth bit, you could do this:
+=== INT 19h memdump
+Let's say you want to examine memory; for example to print some data in memory. You can use INT 0x19:
-    LDA #0
+    LDAH #7        ; Memory dump function
-    SEC         ; set the carry flag
+    LDCL #2        ; Two rows (16 bytes)
-    ROLC A      ; 1st bit is set
+    INT 0x19       ; System services library
-    ROL A       ; 2nd bit is set
+    HALT
-    ROL A       ; 3rd...
-    ROL A       ; 4th...
-    ROL A       ; bit is now moved into 5th position.
-You can use the same pattern to "test" a bit, then use JC or JNC to branch code.
+This looks something like:
-Another great way is a kind of cheap cypher; you can "ROL" a byte before writing it then "ROR" it back later. Unless someone knows what you've done, it //could be// difficult to figure out! This wouldn't stop a dedicated code-breaker, but it will confound almost everyone else.
+: 00 00 00 00 00 00 00 00  | ........
+: 00 00 00 00 00 00 00 00  | ........
-You can also use this to pack or unpack nybbles. This is how 16 color graphics are stored in half the space -- or how two decimal numbers can be encoded in a hexidecimal and read separately. For example?
-        LDAL $F5
-        SHR AL
-        SHR AL
-        SHR AL
-        SHR AL    ; After four shifts, AL contains the "high nybble", i.e. $F.
-        LDAL $F5
-        SHL AL
-        SHL AL
-        SHL AL
-        SHL AL    ; this clears the original top bits in AL,
-        SHR AL
-        SHR AL
-        SHR AL
-        SHR AL    ; After four shifts back right, AL contains the "low nybble", i.e. $5.
-I suppose the first and most common use of these instructions is to pack and unpack data into a byte.