Chastity White Rose

Tag: technology

  • chastdin calculator for RISC-V Assembly

    I really did it this time. I translated all of my Intel Assembly functions into RISC-V Assembly and rebuilt my calculator. It works flawlessly running under the rars simulator.

    To run this example, you need the RARS java archive and a java runtime environment installed on your machine.

    You can get RARS here:

    https://github.com/rarsm/rars

    However, once you do, you can run my program with a command like the following.

    java -jar ~/rars.jar main.s

    # chastelib test suite for RISC-V Assembly in RARS simulator

# this program tests the stdin extension of chastelib

# The same library of functions I commonly use in my Intel Assembly code
# have now been translated to RISC-V.
# All assembly code seen here is for the RARS simulator written in Java.

.data

##################################################################
# chastelib core specific variables                              #
#                                                                #
# These variables are used by the intstr function to convert an  #
# integer to a string and what radix and widthshould be used     #
# width means how many minimum digits including leading zeros    #
##################################################################

int_string: .space 32 #reserve space for 32 bytes for up to 32 bits if printed in binary
int_end: .byte 0 #the terminating zero of the integer string
radix: .byte 2   #the radix the number will be shown in
int_width: .byte 1 #by default

# These variables are for outputting special strings
# such as a newline, space, or a single character based on s0

space: .byte 0x20, 0
line:  .byte 0x0A, 0
char:  .byte 0, 0 

##################################################################
# chastdin specific variables                                    #
#                                                                #
# these variables are used as the default controllers            #
# for the getstr and getline functions                           #
# buf stores keyboard input during those functions               #
# count stores how many bytes were read during system read calls #
# last_char stores the last character read                       #
# usually this will be a space, tab, or newline                  #
##################################################################

buf: .space 0x100
count: .word 0
last_char: .byte 0

# program specific variables
# These variables are for outputting specific messages
# or to simulate user input as integers in the strint function

string0: .ascii "calculator for RISC-V Assembly\n"
string1: .asciz "chastdin (Chastity's STanDard INput) extension\n\n"

string_add: .asciz "add"
string_sub: .asciz "sub"
string_mul: .asciz "mul"
string_div: .asciz "div"
string_rem: .asciz "rem"
string_setradix: .asciz "setradix"

string_help: .asciz "help"
string_exit: .asciz "exit"
string_putstack: .asciz "?"
string_clear: .asciz "clear"

string_prompt: .asciz "->"

string_err: .asciz "Error: invalid number or command: "
string_err1: .asciz "Error: need one number on stack for command: "
string_err2: .asciz "Error: need two numbers on stack for command: "

chastdin_help: .ascii "chastdin is a stack based interactive calculator\n"
              .ascii "that reads stdin for numbers and commands.\n"
              .ascii "Numbers are pushed on the stack for all math.\n"
              .ascii "Each line can contain multiple numbers or commands.\n\n"
              .ascii "Arithmetic commands are add,sub,mul,div,rem\n"
              .ascii "The exit command ends the program\n"
              .ascii "The ? command prints the entire stack\n"
              .asciz "The setradix command changes the radix for input and output\n"

.align 2  # Aligns the next item to a 4-byte (2^2) word boundary
chastack: .space 0x400 #reserve space for RPN calculator stack

.text

la s0, string0
jal putstr

# change radix for this program
li t0, 10    #load t0 register with the new radix
la t1, radix #load t1 register with the address the radix will go to
sb t0, 0(t1) #save t0 register (byte) to address t1

la s11, chastack #s11 will be used as the virtual stack pointer for this program

#print the help message at the beginning of the program
la s0, chastdin_help
jal putstr

#print the initial arrow prompt
la s0, string_prompt
jal putstr

main_loop:

la t1, last_char #load address of last_char
lb t0, 0(t1)     #get the last character

#show the arrow indicating we wait for the user to enter something
#but only show it when the last character is a newline
#otherwise it will print too many if multiple commands were entered on the same line
li t1, 0xA
bne t0, t1, skip_prompt
la s0, string_prompt
jal putstr
skip_prompt:

jal getstr  # read the string from standard input

#load the length of string just entered from (count)
la t1, count            #load address of count into t1
lw t0, 0(t1)            #load number of chars read at (count) address
beq t0, zero, main_loop #restart main_loop on empty string

#jal putline # print extra line for readability
#jal putstr # echo it to standard output
#jal putline

#s0 already contains string that was input
#s1 will be loaded with address of exit string
la s1, string_exit
jal strcmp
# end program if the string entered is equal to string_exit
beq t0, zero, exit

la s1, string_putstack
jal strcmp
beq t0, zero, command_putstack

la s1, string_clear
jal strcmp
beq t0, zero, command_clear

la s1, string_help
jal strcmp
beq t0, zero, command_help

#next we begin checking for actual math commands of arithmetic

la s1, string_add
jal strcmp
beq t0, zero, command_add

la s1, string_sub
jal strcmp
beq t0, zero, command_sub

la s1, string_mul
jal strcmp
beq t0, zero, command_mul

la s1, string_div
jal strcmp
beq t0, zero, command_div

la s1, string_rem
jal strcmp
beq t0, zero, command_rem

la s1, string_setradix
jal strcmp
beq t0, zero, command_setradix


#if the last string entered was not exit or a math command then
#The default command is to turn the argument into a number and push to stack
command_num:

mv s1, s0              #back up this string address to s1 register
jal strint             #try to get a number from the string pointed to by s0 register
beq a0, zero, num_push #branch to number push if zero errors in integer string

la s0, string_err    #load error message
jal putstr           #print error message
mv s0, s1            #load original command string
jal putstr           #print which command failed
jal putline
j num_push_end       #skip the push because this can't be used

num_push:            #push the number to the fake stack
addi s11, s11, 4     #increment the pointer by the size of the native int for this mode
sw s0, 0(s11)        #store the value we converted from the string with strint to this stack space
num_push_end:
j main_loop          #once value is pushed, continue the program

exit:
li a0, 0  #status
li a7, 93 #exit
ecall     #environment call

#################################################################################
# The following functions are used in the calculator program                    #
# The all jump back to the main_loop after they are done                        #
#                                                                               #
#################################################################################

#check if the stack has enough space for the last command
#this will print an error if less than two numbers were on the stack
#when using one of the math commands above

memory_check:

la s10, chastack        #load s10 with chastack address for branch comparison
blt s10, s11, memory_ok # if s10 is less than s11, no errors

print_stack_error:   #otherwise we print error message
la s0, string_err2   #get error message for less than 2 numbers on stack
jal putstr           #print error message
mv s0, s1            #get name of the command used
jal putstr           #print which command failed
jal putline
addi s11, s11, 4     #increment the pointer to what it was before the failed command
j main_loop          #now go back to main loop after error was printed

memory_ok:
sw zero, 4(sp)       #if no error, erase the old top of stack by storing zero
j main_loop          #and continue main_loop as normal


command_putstack: #print all numbers on the stack
la s9, chastack #load s9 with address of chastack
mv s10, s11     #copy value of s11 to s10
command_putstack_loop:

#is s10 equal to the address of stack start?
#if so, end the putstack loop
beq s9, s10 command_putstack_end
lw s0, 0(s10) #load the word at s10 into s0 for printing integer 
addi s10, s10, -4 #subtract the word size from this temp stack index
jal putint
jal putline
j command_putstack_loop
command_putstack_end:
j main_loop




command_clear: #erase all numbers on the stack
la s9, chastack #load s9 with address of chastack
command_clear_loop:

#is s11 equal to the address of stack start?
#if so, end the clear loop
beq s9, s11 command_clear_end
sw zero, 0(s11) #store zero into the word at 0(s11) to erase it
addi s11, s11, -4 #subtract the word size from this temp stack index
j command_clear_loop
command_clear_end:
j main_loop


command_help:
la s0, chastdin_help
jal putstr
j main_loop

#add number on top of stack to the one below it
command_add:
lw t1, 0(s11)     #load the word at this chastack address
addi s11, s11, -4 #subtract the word size from s11
lw t0, 0(s11)     #load the word at this chastack address
add t0, t0, t1    #t0 = t0 + t1
sw t0, 0(s11)     #save the word at this chastack address
j memory_check    #check stack for errors after this command

#add number on top of stack to the one below it
command_sub:
lw t1, 0(s11)     #load the word at this chastack address
addi s11, s11, -4 #subtract the word size from s11
lw t0, 0(s11)     #load the word at this chastack address
sub t0, t0, t1    #t0 = t0 - t1
sw t0, 0(s11)     #save the word at this chastack address
j memory_check    #check stack for errors after this command

#mul number on top of stack to the one below it
command_mul:
lw t1, 0(s11)     #load the word at this chastack address
addi s11, s11, -4 #subtract the word size from s11
lw t0, 0(s11)     #load the word at this chastack address
mul t0, t0, t1    #t0 = t0 * t1
sw t0, 0(s11)     #save the word at this chastack address
j memory_check    #check stack for errors after this command

#divide and store quotient on stack
command_div:
lw t1, 0(s11)     #load the word at this chastack address
addi s11, s11, -4 #subtract the word size from s11
lw t0, 0(s11)     #load the word at this chastack address
divu t0, t0, t1    #t0 = t0 / t1
sw t0, 0(s11)     #save the word at this chastack address
j memory_check    #check stack for errors after this command

#divide and store remainder on stack
command_rem:
lw t1, 0(s11)     #load the word at this chastack address
addi s11, s11, -4 #subtract the word size from s11
lw t0, 0(s11)     #load the word at this chastack address
remu t0, t0, t1   #t0 = t0 % t1
sw t0, 0(s11)     #save the word at this chastack address
j memory_check    #check stack for errors after this command



#pop top of stack and set the current radix to it
#it has error checking and leaves the radix as is
#unless at least one number is on the stack
command_setradix:


la s10, chastack     #load s10 with chastack address for branch comparison
ble s11, s10, change_radix_no # if s11 is less than or equal to chastack address, branch to radix error
change_radix_yes:
lw t0, 0(s11)        #load t0 register with the new radix
la t1, radix         #load t1 register with the address the radix will go to
sb t0, 0(t1)         #save t0 register (byte) to address t1
sw zero, 0(s11)      #erase the old top of stack by storing zero
addi s11, s11, -4
j main_loop          #and continue main_loop as normal
change_radix_no:
la s0,string_err1    #get error message for less than 1 numbers on stack
jal putstr           #print error message
mv s0, s1            #get name of the command used
jal putstr           #print which command failed
jal putline

addi s11, s11, 4     #increment the pointer to what it was before the failed command
j main_loop          #now go back to main loop after error was printed

#################################################################################
# The following functions are independent of a specific RISC-V Operating System #
#                                                                               #
# intstr = convert integer into a string ready for printing                     #
# putint = prints integer using intstr and the OS specific putstr function      #
# strint = convert string into an integer                                       #
#                                                                               #
# The s0 register is used for pass data in or out of these functions            #
# See comments above those specific functions for full details                  #
#################################################################################

# The intstr function does several things at once and is the foundation for all integer output.
# It uses the global radix variable to know which radix or number base to use when turning the integer to a string
# It also uses the global int_width variable to determine how many leading zeros should be used for the string
# The purpose of this is to make numbers look good when lined up when they are printed in a list.
# radices 2 to 36 are supported. Digits higher than 9 will be capital letters

intstr:

la t1, radix     #load address of radix into t1
lb t2, 0(t1)     #load value of radix into t2
la t1, int_width #load address of width into t1
lb t4, 0(t1)     #load value of int_width into t4
li t3, 1         #load current number of digits, always 1

la t1, int_end   #t1=address of terminating zero in string
addi t1, t1, -1  #t1-- to go to lowest digit

digits_start:

remu t0, s0, t2  #t0=remainder of the previous division
divu s0, s0, t2  #s0=s0/t2 (divide s0 by the radix value in t2)

li t5, 10        #load t5 with 10 because RISC-V does not allow constants for branches

blt t0, t5, decimal_digit
bge t0, t5, hexadecimal_digit

decimal_digit:   #we go here if it is only a digit 0 to 9

addi t0, t0, 0x30

j save_digit

hexadecimal_digit:
addi t0, t0, -10
addi t0, t0, 0x41

save_digit:
sb t0, 0(t1)     #store byte from t0 at address t1
beq s0, zero, intstr_end
addi t1, t1, -1
addi t3, t3, 1
j digits_start

intstr_end:

li t0, 0x30
prefix_zeros:
bge t3, t4, end_zeros
addi t1, t1, -1
sb t0, 0(t1) # store byte from t0 at address t1
addi t3, t3, 1
j prefix_zeros
end_zeros:

mv s0, t1

ret

# this function calls intstr to convert the s0 register into a string
# then it uses the system specific putstr call to print the string
# it also uses the stack to save the value of s0 and ra (return address)
# this way, s0 is restored to the value it had before this function
# restoring ra is required because it is modified during calls to other functions

putint:

addi sp, sp, -8
sw ra, 0(sp)
sw s0, 4(sp)

jal intstr
jal putstr

lw ra, 0(sp)
lw s0, 4(sp)
addi sp, sp, 8

ret

# strint takes the string at address pointed to by s0 register
# and then loads the s0 register with an integer equivalent value
# the a0 register is returned with the number of errors that happened
# programs can use this to find if a user entered a valid number
# number is intepreted according to the current radix

strint:

li a0, 0         #load zero into register for error counting

la t1, radix     #load address of radix into t1
lb t2, 0(t1)     #load value of radix into t2

mv t1, s0        #copy string address from s0 to t1
li s0, 0

read_strint:
lb t0, 0(t1)
addi t1, t1, 1
beq t0, zero, strint_end

#if char is below '0' or above '9', it is outside the range of these and is not a digit
li t5, 0x30
blt t0, t5, not_digit
li t5, 0x39
blt t5, t0, not_digit

#but if it is a digit, then correct and process the character
is_digit:
andi t0, t0, 0xF
j process_char

not_digit:
#it isn't a digit, but it could be an alphabet character
#which counts as a digit in a higher base

# if char is below 'A' or above 'Z', it is outside the range of these and is not capital letter
li t5, 0x41
blt t0, t5, not_upper
li t5, 0x5A
blt t5, t0, not_upper

is_upper:
li t5, 0x41
sub t0, t0, t5
addi t0, t0, 10
j process_char

not_upper:

# if char is below 'a' or above 'z', it is outside the range of these and is not lowercase letter
li t5, 0x61
blt t0, t5, not_lower
li t5, 0x7A
blt t5, t0, not_lower

is_lower:
li t5, 0x61
sub t0, t0, t5
addi t0, t0, 10
j process_char

not_lower:

# if we have reached this point, result invalid and end function
# this is only reached if the byte was not a valid digit or alphabet character
j strint_end_error

process_char:

blt t2, t0 strint_end_error #if this value is above or equal to radix, it is too high despite being a valid digit/alpha

mul s0, s0, t2 # multiply s0 by the radix
add s0, s0, t0 # add the correct value of this digit

j read_strint # jump back and continue the loop if nothing has exited it

strint_end_error:  #we jump here if there was an error with one of the chars
addi a0, a0, 1 #add 1 to the a0 register indicating an error occurred

strint_end: #we jump here when no errors happened
ret

###############################################################################
# This putstr function is my most portable function for RISC-V simulators     #
# It calculates the length of a zero terminated string before printing it     #
# This is the same way used in my Intel Assembly programs for DOS and Linux   #
# This function was written to operate the same in both RARS and riscemu      #
###############################################################################

putstr:

mv t1, s0                       # t1 will be used as an index register

putstr_strlen_start:
lb t0, 0(t1)                    # load byte into t0 from address of t1
beq t0, zero, putstr_strlen_end # if t0==0, then we jump to the end of the loop.
addi t1, t1, 1                  # go to next byte
j putstr_strlen_start           # jump to start of the loop
putstr_strlen_end:              

li a0, 1                        # STDOUT file number
mv a1, s0                       # address of string 
sub a2, t1, s0                  # length of string
li a7, 64                       # write call number
ecall                           # environment call

ret

#############################################################################
# The next four 3 functions print things to standard output                 #
# All of them use the putstr function above to achieve the output           #
# They use the stack to preserve the values of the s0 and t1 registers used #
# They also use global variables in the data section                        #
#############################################################################

#the putchar function, which is named after the C language function of the same name
#prints the lowest byte of the s0 register as a byte or character to standard output

putchar:

addi sp, sp, -12
sw ra, 0(sp)
sw s0, 4(sp)
sw t1, 8(sp)

la t1, char
sb s0, 0(t1)
la s0, char
jal putstr

lw ra, 0(sp)
lw s0, 4(sp)
lw t1, 8(sp)
addi sp, sp, 12

ret

# the putspace function prints a space to standard output

putspace:

addi sp, sp, -8
sw ra, 0(sp)
sw s0, 4(sp)

la s0, space
jal putstr

lw ra, 0(sp)
lw s0, 4(sp)
addi sp, sp, 8

ret

# the putline function prints a newline to standard output

putline:

addi sp, sp, -8
sw ra, 0(sp)
sw s0, 4(sp)

la s0, line
jal putstr

lw ra, 0(sp)
lw s0, 4(sp)
addi sp, sp, 8

ret

##########################################################################
# chastdin extension functions                                           #
#                                                                        #
# all functions that deal with getting strings and characters from stdin #
##########################################################################

# the getstr function will read a string into a buffer from stdin
# and return it in the s0 register for printing with the putstr function
# the (count) variable will also return the number of characters

getstr:

li t0, 0                        # use t0 register to track chars read
la a1, buf                      # load address of buffer for read string
li a2, 1                        # read only 1 byte for each env call

getstr_chars:

li a0, 0                        # STDIN file number
li a7, 63                       # read call number
ecall                           # environment call

# Branch to label getstr_end if a0 is less than a2
# a0 is the return value of this environment read call
# as will be -1 on error or 1 if successful
# because we read 1 character at a time

blt a0, a2, getstr_end

# if no error, test range of the last byte

lb t1, 0(a1)      #load byte at address (a1) into t1 register

# if t1 is less than 0x21
# or t1 is more than 0x7E
# branch to function end because it is outside of print range

li t2, 0x21
blt t1, t2, getstr_end
li t2, 0x7E
blt t2, t1, getstr_end

# otherwise, proceed to read more characters
add t0, t0, a0    # add to read counter
addi a1, a1, 1    # add 1 to buffer pointer register a1
j getstr_chars # unconditional jump to getstr_chars

getstr_end:

la t2, count       #load address of count into t2
sw t0, 0(t2)       #store number of chars read at (count) address
la t2, last_char   #load address of last_char into t2
sb t1, 0(t2)       #store last byte at (last_char) address
sb zero, 0(a1)     #store byte zero to terminate string
la s0, buf         #return address of buf in s0 register

ret




# the getline function will read a string into a buffer from stdin
# and return it in the s0 register for printing with the putstr function
# the (count) variable will also return the number of characters
# this function will get the whole line including spaces

getline:

li t0, 0                        # use t0 register to track chars read
la a1, buf                      # load address of buffer for read string
li a2, 1                        # read only 1 byte for each env call

getline_chars:

li a0, 0                        # STDIN file number
li a7, 63                       # read call number
ecall                           # environment call

# Branch to label getline_end if a0 is less than a2
# a0 is the return value of this environment read call
# as will be -1 on error or 1 if successful
# because we read 1 character at a time

blt a0, a2, getline_end

# if no error, test range of the last byte

lb t1, 0(a1)      #load byte at address (a1) into t1 register

# if t1 is less than 0x20
# or t1 is more than 0x7E
# branch to function end because it is outside of print range

li t2, 0x20
blt t1, t2, getline_end
li t2, 0x7E
blt t2, t1, getline_end

# otherwise, proceed to read more characters
add t0, t0, a0    # add to read counter
addi a1, a1, 1    # add 1 to buffer pointer register a1
j getline_chars # unconditional jump to getline_chars

getline_end:

la t2, count       #load address of count into t2
sw t0, 0(t2)       #store number of chars read at (count) address
la t2, last_char   #load address of last_char into t2
sb t1, 0(t2)       #store last byte at (last_char) address
sb zero, 0(a1)     #store byte zero to terminate string
la s0, buf         #return address of buf in s0 register

ret



# Short Description of strlen:
# The strlen function gets the length of string in s0 and returns it in s0
# This is the same algorithm used in my putstr function but is independent of an operating system.

strlen:

mv t1, s0                       # t1 will be used as an index register

strlen_start:
lb t0, 0(t1)                    # load byte into t0 from address of t1
beq t0, zero, strlen_end        # if t0==0, then we jump to the end of the loop.
addi t1, t1, 1                  # go to next byte
j strlen_start                  # jump to start of the loop
strlen_end:              

sub s0, t1, s0                  # return length of string in s0

ret


# Short Description of strcmp:
# strcmp compares the string at s0 to the one at s1
# t0 returns 0 if the strings are the same and non zero if different
# the algorithm is simple but I will explain it for those who are confused

# Long Description of strcmp:
# each byte from each string is loaded into the t0 and t1 registers
# the bytes are compared. if they are different, then we jump to the end
# However, if they are the same, then we check if one of them is zero
# if it is zero, this also jumps to the end of the function
# If neither jump took place, then we jump to the start of the loop
# but when the function finally ends t1 will be subtracted from t0
# this ensures that the t0 register returns zero if the final characters are the same
# a zero result in t0 also guarantees that both strings are equal

strcmp:

mv a0, s0 # move pointer s0 to a0
mv a1, s1 # move pointer s1 to a1

strcmp_start:

#read a byte from each string
lb t0, 0(a0) 
lb t1, 0(a1) 
#if the two bytes are not equal end comparison
bne t0, t1, strcmp_end

#but if they are equal, test for zero
#if one of them is zero, also end the loop
beq t0, zero, strcmp_end

addi a0, a0, 1                  # go to next byte
addi a1, a1, 1                  # go to next byte

j strcmp_start

strcmp_end:

#subtract t1 from t0
#if t0 is still zero after the function returns
#it means that the strings are equal
sub t0, t0, t1

ret

  • What Microsoft Copilot says about Assembly Arithmetic Algorithms

    I tried something new. I asked Microsoft Copilot what it could tell me about my own series of books on Assembly. I have to say I am impressed with the nice summary it came up with. I really think it highlights how unique this series is because it is written from the perspective of my autism and math obsession.

    Assembly Arithmetic Algorithms is a series of assembly‑language programming books written by Chastity White Rose, covering DOS, Windows (32‑ and 64‑bit), and Linux editions. They teach low‑level programming by focusing on arithmetic, binary/hex math, system calls, and how computers actually perform operations like addition, subtraction, multiplication, and division.

    📘 What the books are

    Chastity White Rose has published multiple editions of Assembly Arithmetic Algorithms, each targeting a different operating system:

    1. 16‑bit DOS Edition

    • Teaches how to write .com programs for MS‑DOS.
    • Focuses heavily on binary/hex arithmetic and low‑level operations.
    • Includes explanations of interrupts, pointers, memory addresses, and arithmetic routines.
    • Emphasizes learning how computers “think” numerically.
    • MS-DOS | Definition, Features, Importance, & Facts | Britannica
    • MS-DOS - Wikipedia
    • Difference Between Assembly And Binary at Donna Bull blog
    • Program Development and Execution | Assembly language, Assembly ...

    2. 32‑ and 64‑bit Windows Edition

    • Covers Windows API calls (GetStdHandle, WriteFile, ExitProcess).
    • Introduces registers, stack behavior, and bit operations.
    • Provides “Hello World” examples for both 32‑bit and 64‑bit Windows.
    • Designed for beginners and intermediate programmers wanting deeper control.
    • 理解 Windows API 调用过程 - 厚积薄发 - 开发者Cpp博客
    • Architecture Overview - Win32 apps | Microsoft Learn
    • X64 registers
    • PPT - Introduction to Machine-Level Programming: Basics of x86 ...

    3. 32‑bit Linux Edition (co‑authored with Chandler Klebs)

    • Focuses on POSIX system calls: read, write, open, close, lseek, exit.
    • Includes C programs to help explain assembly routines.
    • Teaches how to write fast, minimal Linux console applications.
    • Manage Your Linux System Resources With These 7 Terminal Commands
    • Timer In Linux Terminal at Rita Skelley blog
    • x86 Assembly Guide-CSDN博客
    • Assembly Language Tutorial No. 1 : Introduction To Registers - YouTube

    🧠 What the books emphasize

    Across all editions, the core themes are:

    • Binary arithmetic (addition, subtraction, multiplication, division)
    • Understanding CPU registers and flags
    • Memory addressing and pointer arithmetic
    • System calls and OS‑level interaction
    • Writing extremely small, efficient programs
    • Learning how computers actually perform math internally

    Chastity frames arithmetic as the foundation of all computation — the CPU’s “native language.”

    📚 Why these books stand out

    • They are modern books about old‑school assembly, which is rare.
    • They teach assembly through arithmetic, not through abstract theory.
    • They are written by a transgender Christian author who blends technical instruction with personal philosophy and creativity.
    • They aim to preserve low‑level programming knowledge that is becoming harder to find.

  • chastdin for FreeBASIC

    I have rewritten my chastdin program (the stack based calculator that reads keyboard input from standard input) into the FreeBASIC programming language. I did it as an exercise to prepare myself for a future book on the BASIC programming language which was my first programming language. FreeBASIC is compatible with QBASIC which is what I first started on. Luckily, BASIC is not so different from C but I had to spend a lot of time on the documentation to refresh my memory in how I used to do things with it.

    Eventually I would like to make a GUI version of this command line calculator. I am trying to take baby steps in working my way into programs that the average person would use. However, command line utilities are still the easiest to build and that is an acceptable place to start.

    main.bas

    #include "chastelib.bi"
#include "chastdin.bi"

dim shared as integer chastack(256)
dim shared as integer csi=0 'Chastity's Stack Index

radix=10

dim as integer a,b
dim shared as string s

sub help()
?  "chastdin is a stack based interactive calculator"
?  "Numbers are pushed on the stack and commands can do math."
?  "It is a fork of chastack that reads from stdin instead of arguments."
?  "Each line can contain multiple numbers or commands."
?
?  "Math commands are add,sub,mul,div,rem"
?  "And use the top two stack numbers for their operations"
?
?  "The setradix command uses the top of stack as the new radix"
?  "The exit command ends the program"
?  "The ? command prints the entire stack"
?
end sub

sub stack_check()
 if csi>0 then
  chastack(csi+1)=0 /'erase old top of stack because command was successful'/
 else
  print "Error: two numbers required for command: ";s
  csi+=1 /'increment the pointer to what it was before the failed command'/
 end if
end sub

help():

while s<>"exit"

s=""

 s=getstr() 'read and ignore empty strings

'print entire stack
if s="?" or s="print" then
 b=csi
 while csi>0
  print intstr(chastack(csi))
  csi-=1
 wend
 csi=b

elseif s="exit" then
exit while

elseif s="help" then
help()

elseif s="setradix" then
 if csi>0 then
 radix=chastack(csi)
 chastack(csi)=0
 csi-=1
 else
  print "Error: need one number on stack for command: ";s
 end if

elseif s="add" then
b=chastack(csi)
csi-=1
a=chastack(csi)
a+=b
chastack(csi)=a
stack_check()

elseif s="sub" then
b=chastack(csi)
csi-=1
a=chastack(csi)
a-=b
chastack(csi)=a
stack_check()

elseif s="mul" then
b=chastack(csi)
csi-=1
a=chastack(csi)
a*=b
chastack(csi)=a
stack_check()

elseif s="div" then
b=chastack(csi)
csi-=1
a=chastack(csi)
a\=b
chastack(csi)=a
stack_check()

elseif s="rem" then
b=chastack(csi)
csi-=1
a=chastack(csi)
a=a mod b
chastack(csi)=a
stack_check()

else

'try to interpret string as a number if not empty
 a=strint(s)
 if strint_errors<>0 or len(s)=0 then
 'print s;" cannot be added to the stack because it is not a valid number"
 else
 csi+=1
 chastack(csi)=a
 print intstr(a);" was added to the stack"
 end if

end if

wend

/'
 This is a FreeBASIC program.

 compile and run as:

 fbc main.bas && ./main
'/

    chastelib.bi

    /'
 global variables to define radix and formatting
 for the intstr function
'/
dim shared as integer radix=2
dim shared as integer int_width=1

/'
 translation of intstr function for FreeBASIC
 by original C programmer Chastity White Rose
'/
function intstr(i as uinteger) as string
 dim as string s=""
 dim as integer w=0
 dim as byte c

 while i<>0 or w<int_width 

  c=i mod radix                  
  i\=radix                     

  if c<10 then 
  c+=48
  else
  c+=55
  end if

  s=chr(c)+s

  w+=1                     
 wend

return s
end function

/'
 global variable for error detection in strint function
 this variable will be zero if last string was a number
'/
dim shared as integer strint_errors=0

/'
 translation of strint function for FreeBASIC
 by original C programmer Chastity White Rose
'/
function strint(s as string) as uinteger
dim as uinteger i=0
dim as integer x=0,y=len(s)
dim as byte c

strint_errors = 0 /' clear errors '/

while x<y

 /' read digit from string '/
 c=s[x]

 /' 0 to 9 '/
 if c >= 48 and c <= 57 then
 c-=48
 /' A to Z '/
 elseif c >= 65 and c <= 90 then
 c-=65
 c+=10
 /' a to z '/
 elseif c >= 97 and c <= 122 then
 c-=97
 c+=10
 /' whitespace '/
 elseif c >= 0 and c <= 32 then
  exit while /' exit correctly at string end '/
 else
  strint_errors+=1
  print "Error: ";chr(s[x]);" is not an alphanumeric character!"
  exit while /' exit at invalid character '/
 end if

 if c>=radix then
  strint_errors+=1
  print "Error: ";chr(s[x]);" is not a valid character for radix ";radix
  exit while /' exit at digit wrong for radix '/
 end if

 /'multiply by radix then add digit'/
 i*=radix
 i+=c

x+=1
wend

return i
end function

    chastdin.bi

    dim shared as string stdin_buf
dim shared as integer stdin_buf_index
dim shared as integer stdin_buf_length=0

function getstr() as string
dim as string s=""         'create empty string
dim as byte c              'temporary byte/char variable

/'
this section gets a line of text
if the length of the string/buffer is 0
'/

if stdin_buf_length=0 then      'check if there are characters in the buf
input "-> ",stdin_buf           'if not, read a line of text
stdin_buf_index=0               'set index to zero
stdin_buf_length=len(stdin_buf) 'set the length
end if

/'
regardless of whether input was added above
or if it still had bytes from the last input
we then extract characters one at a time into the
substring s to be returned from the function
'/

while stdin_buf_index<stdin_buf_length
c=stdin_buf[stdin_buf_index]
stdin_buf_index+=1
if(c>=33) and (c<=126) then
s=s+chr(c)
else
exit while
endif
wend

/'
if the index matches the length of buffer
set length to zero so that more will be read
next time this function is called
'/

if stdin_buf_index=stdin_buf_length then
stdin_buf_length=0
end if

return s
end function

/'
the getline function always gets an entire line of text
I don't really need it but it is here as a reminder of
how to use the input statement in FreeBASIC
'/

function getline() as string
dim as string s=""
input "-> ",stdin_buf
s=stdin_buf
return s
end function

  • chastelib for Pascal Programming Language

    I managed to hack my four functions from chastelib into the Pascal programming language. This program includes the functions and the test suite which works just like the C version. The code is a bit more complex than the C version because strings and characters are handled very differently than they are in the C programming language. The strint function was the hardest to write but it seems to be working according to the standards I require.

    I am doing this for education and possibly a future book on old programming languages. Pascal is nice but I will also be studying BASIC again.

    program chastelib;

const
 string0='Official test suite for the Pascal version of chastelib.'#10;

var //this is the global variable section
 a:integer;
 b:integer;
 
 radix:integer;       //current radix being used
 int_width:integer=1; //global integer width
 strint_errors:integer=0; //error result for strint function

(*
A function to print a string using Pascal's write function.
*)
procedure putstr(s:string);
begin
 write(s);
end;

(*
 a function to return a string form of an integer
 using the global radix variable
*)
function intstr(i:integer):string;
var
 s:string=''; //string that will be built and returned from this function
 width:integer=0; //the current width
 c:integer;
 ch:char;
begin
 while (i>0) or (width<int_width) do
 begin

  c:=i mod radix; //get integer division modulus or remainder
  i:=i div radix; //get integer division quotient

  (*turn remainder c into character ch for digit in this radix*)
  if c<10 then
  begin
   ch:=chr(c+48);
  end
  else
  begin
   ch:=chr(c+55);
  end;

   s:=ch+s; //prefix the string with this character
   width+=1;

 end;

 intstr:=s; //return this string from the function

end;

(*use both putstr and intstr to print an integer*)
procedure putint(i:integer);
begin
 putstr(intstr(i));
end;

(*
Because characters and integers are separate types in Pascal,
it is required to get the ASCII value of characters in the string
for the strint function so I can do the math the same way
as I did in the C version of the function.
*)

function strint(s:string):integer;
var
 i:integer=0; //integer that will be built and returned from this function
 x:integer=1; //index used to scan forward through the string
 c:integer=0;
begin
 strint_errors := 0; (*set zero errors before we parse the string*)
 if (radix<2) or (radix>36 ) then
 begin
  strint_errors+=1;
  writeln('Error: radix ',radix,' is out of range!');
 end;
 while(x<=length(s)) do
 begin
  c:=ord(s[x]);
  if (c>=ord('0')) and (c<=ord('9')) then 
  begin
   c-=ord('0')
  end
  else if (c>=ord('A')) and (c<=ord('Z')) then
  begin
   c-=ord('A');
   c+=10;
  end
  else if (c>=ord('a')) and (c<=ord('z')) then
  begin
   c-=ord('a');
   c+=10;
  end
  
  else if (c < $21 ) then
  begin
   break; (*end loop because we have found whitespace*)
  end
  
  else
  begin
   strint_errors+=1;
   writeln('Error: ',s[x],' is not an alphanumeric character!');break;
  end;
  
  if(c>=radix) then
  begin
   strint_errors+=1;
   writeln('Error: ',s[x],' is not a valid character for radix ',radix);
   break;
  end;
  
  i*=radix; //multiply by the radix
  i+=c;     //add the digit from the character processed

  x:=x+1;
 end;
 strint:=i;
end;




begin
 radix:=16; //set the radix used by both intstr and strint functions

 a:=0;
 b:=strint('100');

 putstr(string0);

 while a<b do
 begin
  radix:=2;
  int_width:=8;
  putint(a);
  putstr(' ');
  radix:=16;
  int_width:=2;
  putint(a);
  putstr(' ');
  radix:=10;
  int_width:=3;
  putint(a);

  if (a>=$20) and (a<=$7E) then
  begin
   putstr(' ');
   putstr(chr(a));
  end;

  putstr(#10);
  a+=1;
 end;
 
 putstr(string0);

end.

(*
 fpc main.pas && ./main
*)

  • Getting Started with Linux

    This is chapter 19 of my Linux Assembly book. However, it has a ton of information about Linux in general. I also cover how to run the Tiny Core Linux distribution inside of the QEMU emulator. This will give current Windows users a way to try out Linux without having to give up Windows until they are sure they no longer need it. Even if you don’t plan to do Assembly programming, this is a great way to get a retro computing feel because a terminal only Linux system is very similar to DOS, except the names of all the commands are different!

    Chapter 19: Getting Started with Linux

    This whole book was written on Debian version 12 (bookworm). This has been my Linux distribution on my desktop computer since at least 2024 when Microsoft Windows decided to overwrite my bootloader when I had a dual boot between Windows and Ubuntu. I installed the newest version of Debian available at the time and have never looked back.

    I got my start in the Linux world back in 2005 during the time of Ubuntu 5.10 (Breezy Badger). Ubuntu was my first distribution and I used it without problem for years. But since Ubuntu was based on Debian, I decided to go with the original distribution. I highly recommend either of them because both of these projects have great websites with detailed installation guides.

    https://www.debian.org/
    https://ubuntu.com/

    If you have an old machine running Windows but it is kind of slow, I recommend following the official instructions and installing one of these distributions of Linux to your hard disk by booting either a live CD or USB drive and following the instructions. I figured it out with no background in Linux when I was 18 years old. They have done great work making Linux easy for beginners.

    But what I am going to do is share a method of trying out Linux for people who don’t have a space computer in their house and they can’t risk deleting Windows because their job or school requires specific Windows software.

    Just as I used a DOS emulator to emulate DOS for the DOS edition of Assembly Arithmetic Algorithms, it is also possible to run Linux in an emulator.

    There are some things you should know about running Linux in an emulator.

    1. Emulators are slower than real hardware and cannot be used to judge Linux. Just because you ran Linux in an emulator and it was slow does not mean that the operating system is a failure or that you should give up the idea.

    2. Emulators have many different options that you should read about and the reason I recommend learning how to use an emulator is because it teaches you to understand hardware better. Files are used as virtual compact disks or hard disks but the emulators see them as being the same as real hardware.

    3. Portability is the best reason to use an emulator. Because an emulator can run software for the same machine type or even a different architecture, you can use the information in this book even if you are running an Intel emulator on an ARM or RISC-V processor.

    The emulator I will be using for this example is called QEMU.

    https://www.qemu.org/
    https://www.qemu.org/docs/master/system/invocation.html

    And the distro I will be using is called Tiny Core Linux.

    http://tinycorelinux.net/

    You will want to go to the downloads page and get the smallest of the three files. It will be named “Core-current.iso”.

    Install QEMU on whatever OS you are currently using. QEMU is available for Windows, Mac, and Linux.

    Once you have QEMU installed and downloaded “Core-current.iso” to a directory somewhere, you can launch it with QEMU by using this command.

    qemu-system-x86_64 -drive file=Core-current.iso,media=cdrom

    You can also use the shorter form of the command which means the same thing.

    qemu-system-x86_64 -cdrom Core-current.iso

    Either way, it will boot into a tiny Linux system that is only a command line. You can use standard Linux commands such as ls,cat,sed,cp,rm,cd, and exit. There is even the “vi” editor built in. If you have not used the vi or vim editors before, don’t worry about it. However, if you have used them, go ahead and practice by making some text files and saving them.

    When you are done using Tiny Core Linux, just use this command:

    sudo poweroff

    How does Tiny Core work?

    Everything will shut down and the emulator will also stop. If you clicked on the QEMU Window and your mouse cursor disappeared, press Ctrl+Alt+G on your keyboard to grab it back from the emulator so you can do other things while the emulator is still running Tiny Core Linux.

    Tiny Core Linux runs entirely in RAM when you run it using only the ISO image for the cdrom drive. Any changes you make will not be saved when you exit the emulator.

    I am sure you are wondering what good an operating system is that doesn’t save your work. For that, I have 2 answers.

    1. Because Tiny Core starts fresh each time using only the files in the CD image, it means each time you have a new chance to do something new and test things without any fear of messing up your system.

    2. There is a way to install it to a hard disk and configure it to save changes. I will be explaining more about this in this chapter.

    Installing Software Temporarily

    Before trying to permanently install Tiny Core to a hard disk, it is important to understand the package manager that it uses. It is called tce-ab. You can run it by its name.

    tce-ab

    It has a lot of text with instructions that let you search for and install packages. For example, on my machine when I booted into Tiny Core on QEMU, I was able to search for and install the “nano” text editor and the “nasm” assembler.

    You can also directly install programs with the tce-load program. This is often faster than navigating the menus of tce-ab.

    tce-load -wi nano

    However, because even previously installed programs will be gone on the next reboot, it is time to teach you how to create a virtual hard disk and reboot into the emulator with a hard disk that we will install to.

    Installing to a Hard Disk

    First, exit the emulator and then use the qemu-img command below to create a 1 Gigabyte empty file that will be used as a hard disk.

    qemu-img create harddisk.img 1G

    qemu-system-x86_64 -drive file=Core-current.iso,media=cdrom -drive file=harddisk.img,format=raw,media=disk

    The Tiny Core install program is ironically not included in the cdrom file we are booting from. Therefore, it becomes necessary to install the installer!

    While you are booted into QEMU with both the cdrom and harddisk images, install the install script with the tce-load command below.

    tce-load -wi tc-install

    It will take some time to install the dependencies of the Tiny Core install script. Notable dependencies are Perl (a popular scriping language) and syslinux (the bootloader).

    After it finished installing, run this command:

    sudo tc-install.sh

    The installer asks a lot of questions about what options you want when you want to install.

    • i for installing from booted cdrom
    • f for frugal hard drive installation
    • 1 for whole disk installation
    • 2 for sda (first hard disk)
    • y for installing the bootloader
    • 3 for the ext4 file system

    Most other options you can leave blank and press enter.

    I know that process may have been a little complex but it highlights the difference between installing Linux and installing Windows.

    You don’t install Windows. It was already on your computer when you bought it. This means somebody else chose all the options for you.

    When you install Linux, you need to know some basic facts or at least google them when in doubt. This takes some time to learn but it gives you unrestricted control in the kind of system you are building for your software development.

    In fact Tiny Core provides a helpful book that explains some of these options.

    http://www.tinycorelinux.net/book.html

    The book covers the graphical interface which is available on a much larger ISO file. I chose to go the pure command line only route and adapt the instructions for the tc-install.sh script which only got a passing mention in the book.

    When you have completed those steps, it is now possible to boot directly into the hard disk without the cdrom!

    qemu-system-x86_64 -drive file=harddisk.img,format=raw,media=disk

    The main benefit of installing to a hard disk instead of just booting from the cd image each time is that any programs you install with tce-ab or tce-load will stay there and be available to use each time you reboot.

    Making a Persistent Home Directory

    However, the files in your home directory are deleted each time you reboot. However, there is an easy fix for this. We will open the bootloader configuration and add an option to restore the backup from sda1.

    First, open the config file:

    nano /mnt/sda1/tce/boot/extlinux/extlinux.conf

    And add this option to the line that starts with APPEND.

    home=sda1

    This means that the home directory will become an actual directory on the hard disk instead of a temporary location only loaded into RAM. With this step completed, you can begin programming in Assembly on your Tiny Core Linux system! Time to install the tools.

    NASM is already in the repository and this is the standard way to install it.

    tce-load -wi nasm

    However, FASM is not available in the repository but it can be easily downloaded from the official website. However, this system only has a terminal with no web browser. Don’t worry, there is a way! We can use the wget command that is already in Tiny Core Linux!

    wget http://flatassembler.net/fasm-1.73.35.tgz

    After the TGZ (Tar with GZip compression) file downloads, we need to extract the files from it.

    tar -xf fasm-1.73.35.tgz

    Now you can change to the fasm directory that was just created.

    cd fasm

    Inside are several files including “fasm” (the actual executable that can assembly all the programs in this book), “fasm.txt” the manual in plain text that describes both how to use FASM and also introduces the Intel instruction set. The “license.txt” may also be of interest.

    To install fasm, we should add it to somewhere where it can be in the current path. Check what the path is currently with this command.

    echo $PATH

    One of the directories that is in the path is “/home/tc/.local/bin”. This gives us the information we need to install fasm permanently there. Just copy fasm there like this:

    cp fasm ~/.local/bin

    Now enter “fasm” as a command and see what happens. If you see the following output, then it was done correctly!

    flat assembler  version 1.73.35
usage: fasm <source> [output]
optional settings:
 -m <limit>         set the limit in kilobytes for the available memory
 -p <limit>         set the maximum allowed number of passes
 -d <name>=<value>  define symbolic variable
 -s <file>          dump symbolic information for debugging

    This means that you can assembly and run any program that I have included in this book, Assembly Arithmetic Algorithms for Linux.

    Keep in mind however that programming in this terminal based environment may feel different because you have to use terminal text editors like vi,vim, or nano. These text editors are just as good as graphical ones except that there is no mouse support. However, I was hoping to give you the retro feeling of programming like a crazy person in the 1980s.

    This is just the tip of the iceberg about what Tiny Core Linux can do. However, I wanted to at least spend this chapter introducing this lesser known distro because it is small enough that it emulates with QEMU flawlessly.

    Although Debian, Ubuntu, Linux Mint, and many others are better than Tiny Core because they have more programs in their repositories, they are too large to emulate because their graphical X Windows System displays use a lot more memory and it is harder for a PC emulator like QEMU to emulate them properly.

    Consider Tiny Core Linux as a way to test the waters and get used to running commands in a Linux terminal before you are ready to install a more mainstream distro like Debian. However, once you have made the jump into the wonderful world of Linux, you will not be disappointed as a programmer because there is no shortage of text editors, assemblers, compilers, and even video games. For example, Final Fantasy 6 and Chrono Trigger from my Steam game collection both work on my Debian Linux system. Ironically, my Windows 11 laptop could not run Chrono Trigger.

    I wrote this chapter to do my small part in the world to help people discover the things I like about Linux and the freedom it offers.

    Tiny Core Linux makefile

    The following makefile is something I use to run commands for emulating Tiny Core Linux inside QEMU. I use it to remind myself what commands I use to set up a new installation of Tiny Core Linux.

    Core-harddisk:
	qemu-system-x86_64 -drive file=harddisk.img,format=raw,media=disk
Core-cdrom:
	qemu-system-x86_64 -drive file=Core-current.iso,media=cdrom
Core-cdrom-short:
	qemu-system-x86_64 -cdrom Core-current.iso
Core-cdrom_and_harddisk:
	qemu-system-x86_64 -drive file=Core-current.iso,media=cdrom -drive file=harddisk.img,format=raw,media=disk
harddisk:
	qemu-img create harddisk.img 1G

    Of course, this chapter also serves as a reminder to myself about how to use Tiny Core Linux and also why it is one of my favorite distributions of Linux. I like it because sometimes I just want to have a text-only system upon which I can improve my scripting and command line usage skills. Modern Linux distros include Graphical User Interfaces where you can point and click your way to doing anything, but from the beginning it was not this way. Therefore, I always promote learning the Linux terminal because it is the one thing that stays consistent and trustworthy no matter which distro you are using at the time.

    I will admit that using the command line is a huge learning curve when you are first getting started. Perhaps I found it easier because I grew up with MS-DOS where text commands were all I had. In any case, knowing how to navigate directories on Linux to edit, copy, rename, and delete files is helpful because there are so many different graphical user interfaces and I can’t remember which menus to click on.

    But the real reason text commands are the best is because text can be copy pasted and then I am able to give you the exact commands to run so that you don’t have to spend months google searching for the right documentation on all these different things!