From 30ff19d7ff423261e437bbcbbf3372e1dfa0e681 Mon Sep 17 00:00:00 2001 From: Annwan Date: Mon, 8 Jun 2026 13:59:47 +0200 Subject: [PATCH] docs: isa: add sized instructions --- Makefile | 67 --------------------- docs/Makefile | 17 ++++++ docs/ain48.sublime-syntax | 2 +- docs/isa.typ | 123 ++++++++++++++------------------------ 4 files changed, 62 insertions(+), 147 deletions(-) delete mode 100644 Makefile create mode 100644 docs/Makefile diff --git a/Makefile b/Makefile deleted file mode 100644 index 2107a49..0000000 --- a/Makefile +++ /dev/null @@ -1,67 +0,0 @@ -# PROGRAMS -CC = clang -CXX = clang++ -LD = clang -AR = ar -RM = rm -f -TYPST = typst - -# COMPILATION FLAGS -LIBS = raylib -ifdef DEBUG -CFLAGS += -Og -g -DDEBUG -else -CFLAGS += -O2 -endif -CFLAGS += -Wall -Wextra -pedantic -std=gnu23 -Iinclude -Werror=return-type $(shell pkg-config --cflags $(LIBS)) -LDFLAGS += $(shell pkg-config --libs $(LIBS)) - -# FILES -SRCS=$(wildcard src/*.c) -DEPS=$(patsubst src/%.c, build/%.d, $(SRCS)) -OBJS=$(patsubst src/%.c, build/%.o, $(SRCS)) - -DOCSRC=$(wildcard docs/*.typ) -DOCS=$(patsubst docs/%.typ, docs/%.pdf, $(DOCSRC)) - -PROGRAM=ain48 - -.PHONY: all build docs clean deepclean setup -all: setup build docs - -setup: compile_flags.txt - -build: $(PROGRAM) - -docs: $(DOCS) - -docs/%.pdf: docs/%.typ - $(TYPST) c $< $@ - -clean: - $(RM) $(OBJS) - $(RM) $(DEPS) - $(RM) compile_flags.txt -deepclean: clean - $(RM) $(PROGRAM) - $(RM) $(DOCS) - -compile_flags.txt: Makefile - printf "%s\n" $(CFLAGS) > $@ - -$(PROGRAM): $(OBJS) - $(LD) $(LDFLAGS) $(OBJS) -o $@ - -build/%.d: src/%.c - @mkdir -p $(@D) - @set -e ; $(RM) $@; \ - $(CC) -M $(CFLAGS) $< > $@.$$$$; \ - sed 's,\($*\)\.o[ :]*,build/\1.o $@ : ,g' < $@.$$$$ > $@; \ - $(RM) $@.$$$$ - -build/%.o: src/%.c - @mkdir -p $(@D) - $(CC) $(CFLAGS) -c $< -o $@ - -include $(DEPS) - diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..74e4ab0 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,17 @@ +# PROGRAMS +RM = rm -f +TYPST = typst + +# FILES +DOCSRC=$(wildcard *.typ) +DOCS=$(DOCSRC:.typ=.pdf) +.PHONY: all docs clean +all: docs + +docs: $(DOCS) + +%.pdf: %.typ + $(TYPST) c $< $@ + +clean: + $(RM) $(DOCS) diff --git a/docs/ain48.sublime-syntax b/docs/ain48.sublime-syntax index 06527bc..405b047 100644 --- a/docs/ain48.sublime-syntax +++ b/docs/ain48.sublime-syntax @@ -6,7 +6,7 @@ file_extensions: scope: source.ain48asm contexts: main: - - match: '(?i)\b(ADD|AEQ|AUT|CESS|CST|DEM|DST|DVD|EI|ET|I|ILG|IMLG|IPLG|IRRV|IVC|LG|MPL|NAM|NCIVC|NCRV|NEC|NEI|NI|NNI|NPI|NUI|PADD|PDEM|PDVD|PI|PILG|PIMLG|PIPLG|PMPL|PRSD|PSTR|RSD|RV|SC|SIM|STR|TSC|UI|VEL)\b' + - match: '(?i)\b(P?[SBQ]?(ADD|DEM|DVD|MPL|RSD|SIM|STR)|AEQ|AN|AUT|[SBQ]?(LG|SC)|CESS|CST|DST|(N?[ENUP])?I|ET|P?I[MP]?LG|IRRV|(NC)?(IVC|RV)|NAM|NEC|TSC|VEL)\b' scope: keyword.operator.word.ain48 - match: '(?i)%([a-z0-7]+)\b' scope: variable.register.ain48 diff --git a/docs/isa.typ b/docs/isa.typ index b17a4a5..72e2432 100644 --- a/docs/isa.typ +++ b/docs/isa.typ @@ -27,6 +27,9 @@ A *byte* (singulus) is the smallest addressable part of memory, that is, a 12-bit binary number. +A *half-word* (binus) is a binary number composed of 2 bytes, that is, a 24 bit +binary number. + A *word* (quaternus) is a binary number composed of 4 bytes, that is, a 48 bit binary number. @@ -79,9 +82,8 @@ memory address. (1, [0]), (1, [0]), (1, [0]), - (1, [0]), - (1, [i#sub[2]\ 0]), - (1, [i#sub[1]\ 0]), + (2, [m]), + (1, [i\ 0]), (1, [s]), (4, [ac]), ), ((4, [r#sub[f]]), (4, [r#sub[2]]), (4, [r#sub[1]]))) @@ -91,33 +93,8 @@ memory address. (1, [0]), (1, [0]), (1, [0]), - (1, [0]), - (1, [i#sub[2]\ 0]), - (1, [i#sub[1]\ 1]), - (1, [s]), - (4, [ac]), - ), ((4, [r#sub[f]]), (4, [r#sub[2]]), (4, text(size: .9em)[imm[0:3]]))) - content((12.25, -6))[or] - byte_diag(voff: -10, ( - (1, [0]), - (1, [0]), - (1, [0]), - (1, [0]), - (1, [0]), - (1, [i#sub[2]\ 1]), - (1, [i#sub[1]\ 0]), - (1, [s]), - (4, [op]), - ), ((4, [r#sub[f]]), (4, text(size: .9em)[imm[0:3]]), (4, [r#sub[1]]))) - content((12.25, -11))[or] - byte_diag(voff: -15, ( - (1, [0]), - (1, [0]), - (1, [0]), - (1, [0]), - (1, [0]), - (1, [i#sub[2]\ 1]), - (1, [i#sub[1]\ 1]), + (2, [m]), + (1, [i\ 1]), (1, [s]), (4, [ac]), ), ((4, [r#sub[f]]), (8, [imm[0:7]]))) @@ -135,13 +112,13 @@ memory address. import cetz.draw: * scale(.65) byte_diag(( - (1, [0]), (1, [0]), (1, [0]), (1, [1]), (1, [0]), (1, [0]), (1, [0]), + (1, [0]), (1, [s]), (4, [r]), ), ((12, [imm[0:11]]),)) @@ -160,9 +137,9 @@ memory address. byte_diag(( (1, [0]), (1, [0]), + (1, [1]), + (1, [1]), (1, [0]), - (1, [1]), - (1, [1]), (1, [0]), (1, [0]), (1, [s]), @@ -176,9 +153,9 @@ memory address. import cetz.draw: * scale(.65) byte_diag(( - (1, [0]), (1, [0]), (1, [1]), + (1, [0]), (1, [s]), (4, [r#sub[d]]), (4, [r#sub[l]]), @@ -291,79 +268,65 @@ Common Notations: h(1em) opts.pos().join(h(2em)) }) -#let aludoc(mnemonic, opnum, opsym, commutative, s) = [ - #optgrid(opt[op][#opnum], opt[s][#s]) +#let aludoc(mnemonic, opnum, opsym, s) = [ + #optgrid(opt[op][#opnum], opt[s][#s], opt[w][2]) / Instruction format: #amal / #raw(mnemonic + " %a, %b, %c", lang: "ain48"): %a ← %b #opsym %c #optgrid( - opt[i#sub[1]][0], - opt[i#sub[2]][0], + opt[i][0], opt[r#sub[f]][a], opt[r#sub[1]][b], opt[r#sub[2]][c], ) - / #raw(mnemonic + " %a, %b, #imm[4]", lang: "ain48"): %a ← %b #opsym imm - #optgrid( - opt[i#sub[1]][0], - opt[i#sub[2]][1], - opt[r#sub[f]][a], - opt[r#sub[1]][b], - opt[imm][imm], - ) - #if not commutative [ - / #raw(mnemonic + " %a, #imm[4], %b", lang: "ain48"): %a ← imm #opsym %b - #optgrid( - opt[i#sub[1]][1], - opt[i#sub[2]][0], - opt[r#sub[f]][a], - opt[r#sub[2]][b], - opt[imm][imm], - ) - ] / #raw(mnemonic + " %a, #imm[8]", lang: "ain48"): %a ← %a #opsym imm - #optgrid(opt[i#sub[1]][1], opt[i#sub[2]][1], opt[r#sub[f]][a], opt[imm][imm]) + #optgrid(opt[i][1], opt[r#sub[f]][a], opt[imm][imm]) ] +#let sized_also(mnem, name) = (also: ( + ( "S" + mnem, "Singulum " + name, [Same as #istr(mnem), but operates on bytes #optgrid(opt[w][0])]), + ( "B" + mnem, "Binum " + name, [Same as #istr(mnem), but operates on half-words #optgrid(opt[w][1])]), + ( "Q" + mnem, "Quaternum " + name, [Alias for the unsized version, operates on words]), +)) #let instructions = ( (mnem: "STR", name: "Subtrahere", sign: true, description: [ Subtract one signed number from another. - #aludoc("STR", "01", "-", false, 1) + #aludoc("STR", "01", "-", 1) / Instruction format: #amal - ]), + ], ..sized_also("STR", "Subtrahere")), (mnem: "ADD", name: "Addere", sign: true, description: [ Add two signed numbers together. - #aludoc("ADD", "00", "+", true, 1) + #aludoc("ADD", "00", "+", 1) / Instruction format: #amal - ]), + ], ..sized_also("ADD", "Addere")), (mnem: "MPL", name: "Multiplicáre", sign: true, description: [ Multiply two signed numbers together. - #aludoc("MPL", "02", "×", true, 1) + #aludoc("MPL", "02", "×", 1) / Instruction format: #amal - ]), + ], ..sized_also("MPL", "Multiplicáre")), (mnem: "RSD", name: "Residérí", sign: true, description: [ Remainder of the Euclidean division of two signed integers. Will raise an arithmetic exception if the right operand is zero. - #aludoc("RSD", "05", "mod", false, 1) + #aludoc("RSD", "05", "mod", 1) / Instruction format: #amal - ]), + ], ..sized_also("RSD", "Residérí")), (mnem: "DVD", name: "Dívidere", sign: true, description: [ Integer part of the Euclidean division of two signed integers. Will raise an arithmetic exception if the right operand is zero. - #aludoc("DVD", "04", "/", false, 1) + #aludoc("DVD", "04", "/", 1) / Instruction format: #amal - ]), + ], ..sized_also("DVD", "Dívidere")), (mnem: "DEM", name: "Ad Dextró Movére", sign: true, description: [ Shift a signed number right by a signed number. Will raise an arithmetic exception if the right operand is negative. - #aludoc("DEM", "06", ">>", false, 1) + #aludoc("DEM", "06", ">>", 1) / Instruction format: #amal - ]), + ], ..sized_also("DEM", "Ad Dextró Movére")), (mnem: "SIM", name: "Ad Sinistró Movére", description: [ Shift a word to the left. Will raise an arithmetic exception if the right operand is negative. - #aludoc("SIM", "07", "<<", false, 0) + #aludoc("SIM", "07", "<<", 0) / Instruction format: #amal - ]), + ], ..sized_also("SIM", "Ad Sinistró Movére")), ( mnem: "ILG", name: "Immediátum Legere", @@ -526,27 +489,27 @@ Common Notations: ]), (mnem: "VEL", name: "Vel", description: [ Bitwise disjunction between two words. - #aludoc("VEL", [11], sym.or, true, 0) + #aludoc("VEL", [11], sym.or, 0) ]), (mnem: "NEC", name: "Nec", description: [ Bitwise negated disjunction between two words - #aludoc("NEC", [15], sym.not + sym.or, true, 0) + #aludoc("NEC", [15], sym.not + sym.or, 0) ]), (mnem: "AUT", name: "Aut", description: [ Bitwise difference between two numbers. - #aludoc("AUT", [12], sym.xor, true, 0) + #aludoc("AUT", [12], sym.xor, 0) ]), (mnem: "AEQ", name: "Aequí", description: [ Bitwise equality between two numbers. - #aludoc("AEQ", [16], [=], true, 0) + #aludoc("AEQ", [16], [=], 0) ]), (mnem: "ET", name: "Et", description: [ Bitwise logical conjunction between two numbers. - #aludoc("ET", [10], sym.and, true, 0) + #aludoc("ET", [10], sym.and, 0) ]), (mnem: "NAM", name: "Non ambó", description: [ Bitwise negated logical conjunction between two numbers. - #aludoc("NAM", [14], sym.not + sym.and, true, 0) + #aludoc("NAM", [14], sym.not + sym.and, 0) ]), ( mnem: "LG", @@ -558,7 +521,8 @@ Common Notations: #optgrid(opt[s][0], opt[r#sub[d]][a], opt[r#sub[a]][b], opt[imm][imm]) / ```ain48 LG %a, (%b)```: This is a special case of ```ain48 LG %a, (%b), #imm[12]``` where imm = 0. ], - ), + ..sized_also("LG", "Legere"), + ), ( mnem: "SC", name: "Scríbere", @@ -569,6 +533,7 @@ Common Notations: #optgrid(opt[s][1], opt[r#sub[d]][a], opt[r#sub[a]][b], opt[imm][imm]) / ```ain48 SC %a, (%b)```: This is a special case of ```ain48 SC %a, (%b), #imm[12]``` where imm = 0 ], + ..sized_also("SC", "Scríbere") ), (mnem: "CESS", name: "Cessáre", description: [ *Privileged* Halts the CPU. @@ -637,7 +602,7 @@ Common Notations: mnem: "P" + m, desc: [ == P#m | Positivós #n - Unsigned version of #m; see #ristr("P" + it.mnem) and #ristr(it.mnem). + Unsigned version of #istr(m); see #ristr("P" + it.mnem) and #ristr(it.mnem). ], ), )