From 905d05624f2b7e9d557614d351a1e3316064e617 Mon Sep 17 00:00:00 2001 From: cinthyr Date: Sun, 31 May 2026 20:53:09 +0200 Subject: [PATCH] docs: Fix a whole lot of typos in the ISA docs --- docs/.template.typ | 1 - docs/isa.typ | 217 ++++++++++++++++++++++----------------------- 2 files changed, 105 insertions(+), 113 deletions(-) diff --git a/docs/.template.typ b/docs/.template.typ index 820fe76..b1c741d 100644 --- a/docs/.template.typ +++ b/docs/.template.typ @@ -13,7 +13,6 @@ set par(justify: true) set heading(numbering: "I.1") show raw: set text(font: "Iosevka Slab", size: 1em / .8) - show math.equation: set text(font: "Fira Math", weight: 400) show title: align.with(center) show strong: text.with(weight: 900) set figure(numbering: "1", placement: auto) diff --git a/docs/isa.typ b/docs/isa.typ index cd9f978..608a039 100644 --- a/docs/isa.typ +++ b/docs/isa.typ @@ -11,7 +11,7 @@ [Internátionális], [Nórmae], grid.cell(rowspan: 2)[--- 48 bit], - [Intstrúctiónum], + [Instrúctiónum], [Numerátiónum], )) @@ -24,14 +24,14 @@ ] = Conventions -A *byte* (singulus) is the smallest adressable part of memory, that is, a 12-bit +A *byte* (singulus) is the smallest addressable part of memory, that is, a 12-bit binary number. A *word* (quaternus) is a binary number composed of 4 bytes, that is, a 48 bit binary number. In memory, multibyte numbers are laid out with the least significant byte at the -lowest memory adress +lowest memory address. = Registers The main registers of the architecture are all word-length: @@ -62,7 +62,7 @@ There is also a 3-bit status register. In instruction diagrams, each large rectangle represents a byte, that are disposed in memory as implied by the reading order, starting at the lowest -memory adress. +memory address. #let instruction_diagram(..bytes, voff: 0) = { import cetz.draw: * @@ -101,8 +101,8 @@ memory adress. (1, [i#sub[2]\ 0]), (1, [i#sub[1]\ 0]), (1, [s]), - (4, [op]), - ), ((4, [r#sub[d]]), (4, [r#sub[2]]), (4, [r#sub[1]]))) + (4, [ac]), + ), ((4, [r#sub[f]]), (4, [r#sub[2]]), (4, [r#sub[1]]))) content((12.25, -1))[or] instruction_diagram(voff: -5, ( (1, [0]), @@ -113,8 +113,8 @@ memory adress. (1, [i#sub[2]\ 0]), (1, [i#sub[1]\ 1]), (1, [s]), - (4, [op]), - ), ((4, [r#sub[d]]), (4, [r#sub[2]]), (4, text(size: .9em)[imm[0:3]]))) + (4, [ac]), + ), ((4, [r#sub[f]]), (4, [r#sub[2]]), (4, text(size: .9em)[imm[0:3]]))) content((12.25, -6))[or] instruction_diagram(voff: -10, ( (1, [0]), @@ -126,7 +126,7 @@ memory adress. (1, [i#sub[1]\ 0]), (1, [s]), (4, [op]), - ), ((4, [r#sub[d]]), (4, text(size: .9em)[imm[0:3]]), (4, [r#sub[1]]))) + ), ((4, [r#sub[f]]), (4, text(size: .9em)[imm[0:3]]), (4, [r#sub[1]]))) content((12.25, -11))[or] instruction_diagram(voff: -15, ( (1, [0]), @@ -137,8 +137,8 @@ memory adress. (1, [i#sub[2]\ 1]), (1, [i#sub[1]\ 1]), (1, [s]), - (4, [op]), - ), ((4, [r#sub[d]]), (8, [imm[0:7]]))) + (4, [ac]), + ), ((4, [r#sub[f]]), (8, [imm[0:7]]))) }, ), ) @@ -197,9 +197,9 @@ memory adress. (1, [0]), (1, [0]), (1, [1]), - (1, [w]), + (1, [s]), (4, [r#sub[d]]), - (4, [r#sub[a]]), + (4, [r#sub[l]]), ), ((12, [imm[0:11]]),)) })) @@ -218,7 +218,7 @@ memory adress. (1, [1]), (1, [1]), (1, [1]), - (3, [op]), + (3, [ac]), )) })) @@ -239,10 +239,10 @@ memory adress. (1, [0]), (1, [0]), (1, [0]), - (1, [I]), (1, [C]), + (1, [E]), (1, [N]), - (1, [Z]), + (1, [U]), (1, [R]), ), ((12, [imm[0:11]]),)) instruction_diagram(((12, [imm[12:23]]),), ((12, [imm[24:35]]),), voff: -3) @@ -260,11 +260,11 @@ memory adress. (1, [1]), (1, [0]), (1, [1]), - (4, [r#sub[a]]), + (4, [r#sub[l]]), (1, [I]), - (1, [C]), + (1, [E]), (1, [N]), - (1, [Z]), + (1, [U]), (1, [R]), )) })) @@ -278,11 +278,11 @@ memory adress. (1, [1]), (1, [1]), (1, [0]), - (4, [r#sub[a]]), + (4, [r#sub[l]]), (1, [I]), - (1, [C]), + (1, [E]), (1, [N]), - (1, [Z]), + (1, [U]), (1, [R]), ), ((12, [imm[0:11]]),)) })) @@ -294,9 +294,9 @@ Common Notations: / ```ain48 %a, %b, %c, ...```: any register a, b, c / ```ain48 #imm[n]```: An immediate (max: n bits) / ```ain48 %0, %nul```: Writes to ```ain48 %0 / %nul``` are discarded -/ ```ain48 (%a)```: The memory at the adress contained by %a -/ ```ain48 (#imm[n])```: The memory at the adress represented by the immediate (max n bits) -/ ```ain48 a_label```: The memory adress correspoding to the label +/ ```ain48 (%a)```: The memory at the address contained by %a +/ ```ain48 (#imm[n])```: The memory at the address represented by the immediate (max n bits) +/ ```ain48 a_label```: The memory address corresponding to the label #let ristr(mnem) = [*#raw(mnem, lang: "ain48")* (#ref(label("ins:" + mnem), form: "page"))] #let istr(mnem) = strong(raw(mnem, lang: "ain48")) @@ -316,7 +316,7 @@ Common Notations: #optgrid( opt[i#sub[1]][0], opt[i#sub[2]][0], - opt[r#sub[d]][a], + opt[r#sub[f]][a], opt[r#sub[1]][b], opt[r#sub[2]][c], ) @@ -324,7 +324,7 @@ Common Notations: #optgrid( opt[i#sub[1]][0], opt[i#sub[2]][1], - opt[r#sub[d]][a], + opt[r#sub[f]][a], opt[r#sub[1]][b], opt[imm][imm], ) @@ -333,51 +333,61 @@ Common Notations: #optgrid( opt[i#sub[1]][1], opt[i#sub[2]][0], - opt[r#sub[d]][a], + 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[d]][a], opt[imm][imm]) + #optgrid(opt[i#sub[1]][1], opt[i#sub[2]][1], opt[r#sub[f]][a], opt[imm][imm]) ] #let instructions = ( (mnem: "STR", name: "Subtrahere", sign: true, description: [ - Subtract one signed number from another + Subtract one signed number from another. #aludoc("STR", "01", "-", false, 1) + / Instruction format: #amal ]), (mnem: "ADD", name: "Addere", sign: true, description: [ Add two signed numbers together. #aludoc("ADD", "00", "+", true, 1) + / Instruction format: #amal ]), (mnem: "MPL", name: "Multiplicáre", sign: true, description: [ - Multiply two signed numbers together + Multiply two signed numbers together. #aludoc("MPL", "02", "×", true, 1) / Instruction format: #amal ]), (mnem: "RSD", name: "Residérí", sign: true, description: [ - Reminder of the euclidian division of two words + 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) + / Instruction format: #amal ]), (mnem: "DVD", name: "Dívidere", sign: true, description: [ - Divide a signed number by another + 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) + / Instruction format: #amal ]), (mnem: "DEM", name: "Ad Dextró Movére", sign: true, description: [ - Shift a signed number left by a signed number. + 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) + / Instruction format: #amal ]), (mnem: "SIM", name: "Ad Sinistró Movére", description: [ - Shift a word to the left + Shift a word to the left. + Will raise an arithmetic exception if the right operand is negative. #aludoc("SIM", "07", "<<", false, 0) + / Instruction format: #amal ]), ( mnem: "ILG", name: "Immediátum Legere", sign: true, description: [ - Load a signed immediate value into a register + Load a signed immediate value into a register. / ```ain48 ILG %a, #imm[12]```: %a ← imm / Instruction format: #ipl #optgrid(opt[s][1], opt[r][a], opt[imm][imm]) @@ -386,7 +396,7 @@ Common Notations: #optgrid(opt[s][1], opt[r][a], opt[imm][imm]) The assembler has freedom to choose the appropriate format given the size of the immediate. The mnemonics #ristr("IMLG") and #ristr("IPLG") also exist to allow - the programmer to explicitely request one format or the other: #istr("IMLG") uses #iml and + the programmer to explicitly request one format or the other: #istr("IMLG") uses #iml and #istr("IPLG") uses #ipl. ], also: ( @@ -398,15 +408,10 @@ Common Notations: mnem: "I", name: "Íre", description: [ - Go to + Go to (jump to) an instruction other than the one immediately following this instruction. / ```ain48 I a_label```: %ia ← a_label - / Instruction Format: #asli + / Instruction format: #asli #optgrid( - opt[I][1], - opt[C][0], - opt[N][0], - opt[Z][0], - opt[R][0], opt[imm][a_label], ) Some assemblers may opt to assemble calls to nearby labels as if they were of @@ -414,44 +419,24 @@ Common Notations: / ```ain48 I #imm[48]```: %ia ← imm\ / Instruction Format: #asli #optgrid( - opt[I][1], - opt[C][0], - opt[N][0], - opt[Z][0], - opt[R][0], opt[imm][a_label], ) / ```ain48 I %a```: %ia ← %a\ / Instruction Format: #aslr #optgrid( - opt[I][1], - opt[C][0], - opt[N][0], - opt[Z][0], - opt[R][0], opt[r#sub[a]][a], ) / ```ain48 I %nul, #imm[12]```: %ia ← %ia + %a / Instruction Format: #asrd #optgrid( - opt[I][1], - opt[C][0], - opt[N][0], - opt[Z][0], - opt[R][0], opt[r#sub[a]][0], opt[imm][imm], ) - This is a special case of the format just below, where becasue offsetting from - %nul is useless, we instead understand it as an offset from %ia + This is a special case of the format just below, where because offsetting from + %nul is useless, we instead interpret it as an offset from %ia. / ```ain48 I %a, #imm[12]```: %ia ← %a + imm / Instruction Format: #asrd #optgrid( - opt[I][1], - opt[C][0], - opt[N][0], - opt[Z][0], - opt[R][0], opt[r#sub[a]][a], opt[imm][imm], ) @@ -462,23 +447,23 @@ Common Notations: "UI", "Si nullus est íre", [ - Used like #istr("I") but only jump if the zero bit of the staus flag is set.\ - #optgrid(opt[I][0], opt[Z][1]) + Used like #istr("I"), but only jump if the zero bit of the status flag is set.\ + #optgrid(opt[I][0], opt[U][1]) ], ), ( "NUI", "Si nón nullus est íre", [ - Used like #istr("I") but only jump if the zero bit of the status flag is not set.\ - #optgrid(opt[I][1], opt[Z][1]) + Used like #istr("I"), but only jump if the zero bit of the status flag is not set.\ + #optgrid(opt[I][1], opt[U][1]) ], ), ( "NI", "Si negatívus est íre", [ - Used like #istr("I") but only jump if the negative bit of the status flag is set.\ + Used like #istr("I"), but only jump if the negative bit of the status flag is set.\ #optgrid(opt[I][0], opt[N][1]) ], ), @@ -486,7 +471,7 @@ Common Notations: "NNI", "Si nón negatívus est íre", [ - Used like #istr("I") but only jump if the negative bit of the status flag is not set.\ + Used like #istr("I"), but only jump if the negative bit of the status flag is not set.\ #optgrid(opt[I][1], opt[N][1]) ], ), @@ -494,15 +479,15 @@ Common Notations: "EI", "Si excedit íre", [ - Used like #istr("I") but only jump if the carry bit of the status flag is set.\ - #optgrid(opt[I][0], opt[C][1]) + Used like #istr("I"), but only jump if the carry bit of the status flag is set.\ + #optgrid(opt[I][0], opt[E][1]) ], ), ( "NEI", "Si nón excedit íre", [ - Used like #istr("I") but only jump if the carry bit of the status flag is not set.\ + Used like #istr("I"), but only jump if the carry bit of the status flag is not set.\ #optgrid(opt[I][1], opt[C][1]) ], ), @@ -510,22 +495,22 @@ Common Notations: "PI", "Si positívus est íre", [ - Used like #istr("I") but only jump if neither the zero nor negative flags of the status + Used like #istr("I"), but only jump if neither the zero nor negative flag of the status flag is set. - #optgrid(opt[I][1], opt[N][1], opt[Z][1]) + #optgrid(opt[I][1], opt[N][1], opt[U][1]) ], ), ( "NPI", "Si nón positívus est íre", [ - Used like #istr("I") but only jump if either the zero or negative flags of the status - flag are set. - #optgrid(opt[I][0], opt[N][1], opt[Z][1]) + Used like #istr("I"), but only jump if either the zero or negative flag of the status + flag is set. + #optgrid(opt[I][0], opt[N][1], opt[U][1]) ], ), ("IVC", "Invocáre", [ - Used like #istr("I") but sets up a function environment prior to jumping:\ + Used like #istr("I"), but sets up a function environment prior to jumping:\ (%it) ← %ia; %it ← %it - 4 #optgrid(opt[R][1]) @@ -539,23 +524,26 @@ Common Notations: Invoke a kernel space function, see your operating system's ABI for more details. / Instruction format: #asss - #optgrid(opt[op][3]) + #optgrid(opt[ac][3]) / ```ain48 NCIVC```: Perform a kernel call. ], ), (mnem: "IRRV", name: "De Interruptó Reveníre", description: [ - *Priviledged* - Instrucion used to exit from the interrupt handler. - #optgrid(opt[op][4]) + *Privileged* + Instruction used to exit from the interrupt handler. + / Instruction format: #asss + #optgrid(opt[ac][4]) + / ```ain48 IRRV```: Return from an interrupt. ]), (mnem: "NCRV", name: "De Nucleó Reveníre", description: [ - *Priviledged* - Return to user space after a system call + *Privileged* + Return to user space after a system call. / Instruction Format: #asss - #optgrid(opt[op][2]) + #optgrid(opt[ac][2]) + / ```ain48 IRRV```: Return from kernelspace. ]), (mnem: "VEL", name: "Vel", description: [ - Bitwise disjunction between two words + Bitwise disjunction between two words. #aludoc("VEL", [11], sym.or, true, 0) ]), (mnem: "NEC", name: "Nec", description: [ @@ -582,51 +570,56 @@ Common Notations: mnem: "LG", name: "Legere", description: [ - Read a word from memory + Read a word from memory. / Instruction Format: #amls / ```ain48 LG %a, (%b), #imm[12]```: %a ← (%b + imm) - #optgrid(opt[w][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 + #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. ], ), ( mnem: "SC", name: "Scríbere", description: [ - Write a word to memory + Write a word to memory. / Instruction Format: #amls / ```ain48 SC %a, (%b), #imm[12]```: (%b + imm) ← %a - #optgrid(opt[w][1], opt[r#sub[d]][a], opt[r#sub[a]][b], opt[imm][imm]) + #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 ], ), (mnem: "CESS", name: "Cessáre", description: [ - Halts Execution of the process + *Privileged* Halts the CPU. / Instruction Format: #asss - #optgrid(opt[op][7]) + #optgrid(opt[ac][7]) / ```ain48 CESS```: Pause execution. ]), (mnem: "RV", name: "Reveníre", description: [ - Returns from a subroutine. - / Instruction Format: #asss - #optgrid(opt[op][0]) - / ```ain48 RV```: %it ← %it - 4; %ia ← (%it) + Returns from a subroutine. + / Instruction Format: #asss + #optgrid(opt[ac][0]) + / ```ain48 RV```: %it ← %it - 4; %ia ← (%it) ]), (mnem: "CST", name: "Construere", description: [ - Push the contents of a register onto the stack: - / ```ain48 CST %a```: This instruction is a macro implemented as follows:\ - #raw(block: true, "SC %a, (%it)\nPSTR %it, #4", lang: "ain48") + Push the contents of a register onto the stack. + / ```ain48 CST %a```: This instruction is a macro implemented as follows:\ + #raw(block: true, "SC %a, (%it)\nPSTR %it, #4", lang: "ain48") ]), (mnem: "DST", name: "Destruere", description: [ - Push the contents of a register onto the stack: - / ```ain48 DST %a```: This instruction is a macro implemented as follows:\ - #raw(block: true, "PADD %it, #4\nLG %a, (%it)", lang: "ain48") + Pop the contents of the top of the stack into a register. + / ```ain48 DST %a```: This instruction is a macro implemented as follows:\ + #raw(block: true, "PADD %it, #4\nLG %a, (%it)", lang: "ain48") ]), (mnem: "TSC", name: "Transcríbere", description: [ - Copy between registers - / ```ain48 TSC %a, %b```: %a ← %b. Macro for ```ain48 VEL %a, %b, %nul``` - ] - ), + Copy between registers. + / ```ain48 TSC %a, %b```: %a ← %b. + This instruction is a macro implemented as ```ain48 VEL %a, %b, %nul```. + ]), + (mnem: "AN", name: "Actió Nulla", description: [ + Do nothing except increment the instruction counter. + / ```ain48 AN```: Do nothing. + This instruction is a macro implemented as ```ain48 IPLG %0, #0```. + ]), ) #instructions.map( @@ -643,7 +636,7 @@ Common Notations: == P#(it.mnem) | Positívós #it.name #label("ins:P" + it.mnem) Same form(s) as #istr(it.mnem) but with s = 0\ - Unsigned version of #ristr(it.mnem) + Unsigned version of #ristr(it.mnem). ])) } if it.keys().contains("also") { @@ -662,7 +655,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 #m; see #ristr("P" + it.mnem) and #ristr(it.mnem). ], ), )