From: bylex <mbilek06@gmail.com>
Date: Sun, 13 Apr 2025 18:29:29 +0000 (+0200)
Subject: Add docs, update gitignore
X-Git-Url: https://git.bylex.cz/?a=commitdiff_plain;h=cec0ec48f90ac5f598191a85044857ed51ab27e0;p=maturita.git

Add docs, update gitignore
---

diff --git a/docs.groff b/docs.groff
new file mode 100644
index 0000000..aa0d732
--- /dev/null
+++ b/docs.groff
@@ -0,0 +1,118 @@
+.uh
+.pp
+Dokumentace maturitniho projektu
+.sh 1 "Uvod"
+.pp
+Tento kratky dokument obsahuje dokumentaci maturitniho projektu
+.br
+Zdrojovy kod je dostupny na odkazu
+.q "https://git.bylex.cz/?p=maturita.git"
+.sh 1 "Assembler"
+.pp
+Cast programu, ktera zpracovava lidsky-citelny kod na mezikod, ktery je pote interpretererem spusteny
+.sh 2 "Jazyk"
+.pp
+Pouzivany jazyk je strukturovany podobne jako jine, jiz existujici jazyky rodiny Assembly
+.br
+Jedine povolene instrukce jsou ty, ktere jsou definovane uvnitr souboru
+.q "common.h"
+ostatni instrukce produkuji bud nepouzitelny vystupni soubor nebo hned zpusobi chybu programu
+.br
+Jednoduche priklady pouziti lze videt v souborech
+.np
+test.s
+.np
+test_gfx.s
+.np
+test_pic.s
+.np
+test_random.s
+.np
+test_stack.s
+.sh 3 "Instrukce"
+.pp
+Popis jednotlivych instrukci se nachazi v komentarich uvnitr souboru
+.q "opcodes.h"
+.sh 3 "Komentare"
+.pp
+Komentare se znaci znakem
+.q "#"
+.br
+Komentar muze byt
+.i pouze
+na samostatnem radku
+.sh 3 "Organizace pameti"
+.pp
+Pamet je bezne organizovana od adresy 0 dal, ale toto je mozne zmenit pomoci operatoru
+.q "."
+.br
+Pokud assembler narazi na tento operator, posune kod na dalsich radkach na prislusnou adresu, adresa se zadava jako decimalni cislo
+.br
+.b "Assembler neresi kolize pametovych prostoru, je nutne, aby programator pocital s delkou sveho kodu a upravil organizaci pameti odpovidajicim zpusobem"
+.sh 3 "Labely"
+.pp
+Labely lze definovat pomoci
+.q "$"
+a lze je pouzit pro instrukce
+.q "jmp" a .q "jez"
+.br
+Slouzi pro zjednoduseni prace programatora, kdo diky nim nemusi manualne zjistovat adresu pameti destinace skoku
+.sh 2 "Pouziti v prikazove radce"
+.pp
+Program assembler je volan s 2 parametry
+.np
+Vstupni soubor
+.np
+Vystupni soubor
+.sh 1 "Interpreter"
+.pp
+Interpreter spousti soubory vytvorene interpreterem, teoreticky i manualnr vytvorene soubory, za predpokladu ze jsou stale platne
+.sh 2 "Pouziti v prikazove radce"
+.pp
+Program interpreter je volan s 2 parametry
+.np
+Vstupni soubor
+.np
+Volba rychlosti - ("--fast", "--info", "--debug")
+.sh 2 "Format souboru"
+.pp
+Soubor ma delku presne 128KiB - 65536 16-bit cisel
+.br
+Uvnitr se nachazi instrukce a data, nejsou nijak oddelena a je tudiz zodpovednosti programatora, aby zajistil, ze se interpreter nedostane k castem kodu, ktere obsahuji data programu a nebude se je snazit spoustet
+.br
+.b "Program neobsahuje zadnou ochranu proti spatnemu kodu ani zadnou schopnost zpracovavat vyjimky"
+.br
+Instrukce ma 4 byty - prvni byte obsahuje kod instrukce, dalsi 3 jsou mozne argumenty - viz. soubor
+.q "opcodes.h"
+a
+.q "common.c"
+.sh 2 "Rezimy spusteni"
+.pp
+Program podporuje 3 rezimy spusteni, voli se pomoci druheho parametru na prikazove radce
+.sh 4 "Fast"
+.pp
+Nejrychlejsi rezim spusteni, zaroven rezim, ktery je zvolen pokud chybi 2. parametr
+.sh 4 "Info"
+.pp
+Rezim, ktery poskytuje trochu informaci o bezicim programu
+.br
+Muze byt uzitecny napriklad pri hledani zacykleni, ktere se objevi az po dlouhe dobe pri pouziti rezimu debug
+.br
+Ukazane informace obsahuji
+.np
+Pocet jiz spustenych instrukci
+.np
+Aktualne spoustenou adresu
+.sh 4 "Debug"
+.pp
+Nejpomalejsi rezim spusteni, umoznuje zasahovat do programu
+.sh 3 "Pouziti debuggeru"
+.pp
+Debugger je aktivni pouze v debug rezimu, ovlada se pomoci zkratek zobrazenych pri chodu
+.br
+Pokud nejsou v programu zadne aktivni breakpointy, tak se program prepne do rychleho rezimu, protoze jiz neni mozne program dal pres debugger nijak ovladat
+.br
+Prikaz
+.q "disassemble"
+.b nevytvari
+presnou kopii puvodniho souboru - tzn. nedokaze zpetne doplnit labely ani komentare