From 39b8996f9c7c5dd10dd5a06dd39984496e860c84 Mon Sep 17 00:00:00 2001 From: minjaesong Date: Sat, 25 Sep 2021 14:48:02 +0900 Subject: [PATCH] doc --- doc/implementation.tex | 72 +++++++++++++++++++++++------------------- doc/tsvmman.idx | 12 +++++-- doc/tsvmman.ilg | 6 ++-- doc/tsvmman.ind | 26 +++++++++++++-- doc/tsvmman.tex | 4 ++- doc/tvdos.tex | 68 +++++++++++++++++++++++++++++++++++++-- 6 files changed, 143 insertions(+), 45 deletions(-) diff --git a/doc/implementation.tex b/doc/implementation.tex index efa9774..33dc258 100644 --- a/doc/implementation.tex +++ b/doc/implementation.tex @@ -6,32 +6,33 @@ Unlike the name suggests, Serial Communication is not at all \emph{serial}; it's \section{Concept of Block Communication} -Sender and Receiver are somehow connected and the commuication channel between two devices are open as long as both sides are connected and being recognised. There are two blocks per port: send-block and receive-block, and the contents of the blocks are memory-mapped\footnote{Both blocks are mapped to the same port; writing to the address writes to the send-block while reading reads from the receive-block. Reading from write-block or writing to the read-block is not possible}. \emph{Write} writes sender's send-block onto the receiver's receive-block while \emph{Read} pulls the message from the receiver's send-block and writes to sender's receive-block. +\index{block communication}Sender and Receiver are somehow connected and the communication channel between two devices are open as long as both sides are connected and being recognised. There are two blocks per port: send-block and receive-block, and the contents of the blocks are memory-mapped\footnote{Both blocks are mapped to the same port; writing to the address writes to the send-block while reading reads from the receive-block. Reading from write-block or writing to the read-block is not possible}. \emph{Write} writes sender's send-block onto the receiver's receive-block while \emph{Read} pulls the message from the receiver's send-block and writes to sender's receive-block. While read/write is being processed, each side emits ``busy'' flag indicating they are \emph{busy}. Sending/receiving data while one side is busy is considered as an undefined behaviour. -\section{The COM-library} +\section{The Com Library} -portNo is a number of the port in 0--3, 0 being the first port. +\index{com (library)}portNo is a number of the port in 0--3, 0 being the first port. \begin{outline} \1\textbf{sendMessage}(portNo: Int, message: String) -\\sends message to the port and returns status code the other machine emits +\\Sends message to the port and returns status code the other machine emits. \1\textbf{fetchResponse}(portNo: Int) -\\fetches the message composed by other device to this machine +\\Fetches the message composed by other device to this machine. \1\textbf{sendMessageGetBytes}(portNo: Int, message: String) -\\sends message, waits for responce, then returns the received message +\\Sends message, waits for responce, then returns the received message. \1\textbf{waitUntilReady}(portNo: Int) -\\blocks the program until the other device is ready +\\Blocks the program until the other device is ready. \1\textbf{pullMessage}(portNo: Int) -\\make other device to initiate sending and returns the message receive from the other device. NOTE: this is not a function you're looking for it you're just getting the response after the sendMessage; use fetchResponse for that +\\Make other device to initiate sending and returns the message receive from the other device. +\\NOTE: this is not a function you're looking for it you're just getting the response after the sendMessage; use fetchResponse for that. \1\textbf{getStatusCode}(portNo: Int) -\\returns the status code of the other device +\\Returns the status code of the other device. \1\textbf{getDeviceStatus}(portNo: Int) -\\returns the status message of the other device. Different types of devices may have different messages +\\Returns the status message of the other device. Different types of devices may have different messages. \1\textbf{areYouThere}(portNo: Int) -\\returns true if there is other device connected and is working +\\Returns true if there is other device connected and is working. \end{outline} @@ -76,29 +77,17 @@ if (0 == status){ \section{Communication MMIO and How It Actually Works} -The status flags and transfer/receive blocks are memory-mapped to these address: +\index{MMIO-com}The status flags and transfer/receive blocks are memory-mapped to these address: \footnote{RW stands for read-write status. RW means both reading and writing is posseble, RO means it's read-only} \begin{tabulary}{\textwidth}{rcL} Address & RW & Description \\ \hline --4077 & RW & Status Code (-128--127) for Writing Port 1 \\ --4078 & RW & Status Code (-128--127) for Writing Port 2 \\ --4079 & RW & Status Code (-128--127) for Writing Port 3 \\ --4080 & RW & Status Code (-128--127) for Writing Port 4 \\ --4081 & RO & Status Code (-128--127) of the Receiver 1 \\ --4082 & RO & Status Code (-128--127) of the Receiver 2 \\ --4083 & RO & Status Code (-128--127) of the Receiver 3 \\ --4084 & RO & Status Code (-128--127) of the Receiver 4 \\ --4085..-4086 & RO & Transfer Status Bits for Port 1 \\ --4087..-4088 & RO & Transfer Status Bits for Port 2 \\ --4089..-4090 & RO & Transfer Status Bits for Port 3 \\ --4091..-4092 & RO & Transfer Status Bits for Port 4 \\ --4093 & RW & Transfer Control for Port 1 \\ --4094 & RW & Transfer Control for Port 1 \\ --4095 & RW & Transfer Control for Port 1 \\ --4096 & RW & Transfer Control for Port 1 \\ +-4077..-4080 & RW & Status Code (-128--127) for Writing Port 1--4 \\ +-4081..-4084 & RO & Status Code (-128--127) of the Receiver 1--4 \\ +-4085..-4092 & RO & Transfer Status Bits for Port 1--4 (two bytes per port) \\ +-4093..-4096 & RW & Transfer Control for Port 1--4 \\ -4097..-8192 & RW & Message Block for Port 1 \\ -8193..-12288 & RW & Message Block for Port 2 \\ -12289..-16384 & RW & Message Block for Port 3 \\ @@ -171,8 +160,11 @@ The com-port will behave differently if you're writing or reading on the address \chapter{Human Interface} +\section{Keyboard} -\section{Keycodes} +TODO + +\subsection{Keycodes} \index{keycodes}This is a table of keycodes recognised by the LibGDX, a framework that \thismachine\ runs on. @@ -291,12 +283,21 @@ F12 & 142 \\ \end{longtable} +\section{Mouse} + +TODO + + \chapter{Text and Graphics Display} +TODO: Textbuf, pixelbuf, draw order +\section{Text Buffer} -\section{Code Page} +TODO + +\subsection{Code Page} \label{codepage} \index{code page}By default \thismachine\ uses slightly modified version of CP-437, this is a character map of it: @@ -308,7 +309,12 @@ F12 & 142 \\ } \newpage -\section{Colour Palette} + +\section{Frame Buffer} + +TODO + +\subsection{Colour Palette} \label{colourpalette} \index{colour palette}By default the reference graphics adapter of the \thismachine\ uses following colour palette: @@ -316,7 +322,7 @@ F12 & 142 \\ {\centering \includegraphics[width=\linewidth]{tsvmpal.png} \captionof{figure}{\thismachine\ Colour Palette} -\label{fig:codepage} +\label{fig:colourpalette} } {\centering @@ -612,7 +618,7 @@ F12 & 142 \\ \section{Graphics MMIO} - +\index{MMIO-graphics} \begin{tabulary}{\textwidth}{rL} Address & Description \\ diff --git a/doc/tsvmman.idx b/doc/tsvmman.idx index 49016e5..5d370a5 100644 --- a/doc/tsvmman.idx +++ b/doc/tsvmman.idx @@ -1,3 +1,11 @@ -\indexentry{keycodes|hyperpage}{13} +\indexentry{block communication|hyperpage}{8} +\indexentry{com (library)|hyperpage}{8} +\indexentry{MMIO-com|hyperpage}{10} +\indexentry{keycodes|hyperpage}{12} \indexentry{code page|hyperpage}{14} -\indexentry{colour palette|hyperpage}{15} +\indexentry{colour palette|hyperpage}{16} +\indexentry{MMIO-graphics|hyperpage}{18} +\indexentry{boot process|hyperpage}{21} +\indexentry{filesystem (DOS)|hyperpage}{23} +\indexentry{filesystem (library)|hyperpage}{23} +\indexentry{gl (DOS)|hyperpage}{24} diff --git a/doc/tsvmman.ilg b/doc/tsvmman.ilg index 251ff27..34039b3 100644 --- a/doc/tsvmman.ilg +++ b/doc/tsvmman.ilg @@ -1,6 +1,6 @@ This is makeindex, version 2.15 [TeX Live 2021] (kpathsea + Thai support). -Scanning input file tsvmman.idx....done (3 entries accepted, 0 rejected). -Sorting entries....done (5 comparisons). -Generating output file tsvmman.ind....done (10 lines written, 0 warnings). +Scanning input file tsvmman.idx....done (11 entries accepted, 0 rejected). +Sorting entries....done (38 comparisons). +Generating output file tsvmman.ind....done (30 lines written, 0 warnings). Output written in tsvmman.ind. Transcript written in tsvmman.ilg. diff --git a/doc/tsvmman.ind b/doc/tsvmman.ind index 625c9f5..9a823b7 100644 --- a/doc/tsvmman.ind +++ b/doc/tsvmman.ind @@ -1,10 +1,30 @@ \begin{theindex} - \item code page, \hyperpage{14} - \item colour palette, \hyperpage{15} + \item block communication, \hyperpage{8} + \item boot process, \hyperpage{21} \indexspace - \item keycodes, \hyperpage{13} + \item code page, \hyperpage{14} + \item colour palette, \hyperpage{16} + \item com (library), \hyperpage{8} + + \indexspace + + \item filesystem (DOS), \hyperpage{23} + \item filesystem (library), \hyperpage{23} + + \indexspace + + \item gl (DOS), \hyperpage{24} + + \indexspace + + \item keycodes, \hyperpage{12} + + \indexspace + + \item MMIO-com, \hyperpage{10} + \item MMIO-graphics, \hyperpage{18} \end{theindex} diff --git a/doc/tsvmman.tex b/doc/tsvmman.tex index e03b029..66713a6 100644 --- a/doc/tsvmman.tex +++ b/doc/tsvmman.tex @@ -67,6 +67,7 @@ %% Idioms %% \hyphenation{Java-script} \hyphenation{ECMA-script} +\hyphenation{name-space} \newcommand\forceindent{\hskip1.5em} @@ -167,6 +168,7 @@ % The title \newcommand{\thismachine}{TSVM} +\newcommand{\thedos}{TVDOS} \newcommand{\tsvmver}{1.2} \newcommand{\theedition}{Zeroth Edition} \newcommand{\thepublishingdate}{0000-00-00} @@ -215,7 +217,7 @@ \chapter{Virtual Machine} \input{implementation} -\part{TVDOS} +\part{\thedos} \input{tvdos} \part*{Bibliography} diff --git a/doc/tvdos.tex b/doc/tvdos.tex index 8669cd2..93512ca 100644 --- a/doc/tvdos.tex +++ b/doc/tvdos.tex @@ -1,7 +1,69 @@ \chapter{Introduction} -TVDOS is a Disk Operating System (usually) bundled with the distribution of the \thismachine. +\thedos\ is a Disk Operating System (usually) bundled with the distribution of the \thismachine. -All TVDOS-related features requires the DOS to be fully loaded. +All \thedos-related features requires the DOS to be fully loaded. -\chapter{Filesystem} + + + +\chapter{Bootstrapping} + +\index{boot process}\thedos\ goes through follwing progress to deliver the \code{A:/} prompt: + +\section{Probing Bootable Devices} +BIOS + +\section{The Bootloader} +LOADBOOT + +Then the Bootsector will try to read and execute \code{A:/tvdos/TVDOS.SYS} + +\section{TVDOS.SYS} +\thedos.SYS will load system libraries and variables and then will try to run the boot script by executing \code{A:\\AUTOEXEC.BAT} + +\section{AUTOEXEC.BAT} + +AUTOEXEC can setup user-specific variables (e.g. keyboard layout) and launch the command shell of your choice, \code{COMMAND} is the most common shell. + +Variables can be set or changed using \textbf{SET} commands. + + + +\chapter{DOS Commands} + + +\chapter{DOS Libraries} + +\section{Filesystem} + +\index{filesystem (DOS)}Each port is assigned to different drive letters, and the device currently booted on is always drive \textbf{A}. + +\section{The Filesystem Library} + +\index{filesystem (library)}Functions in the filesystem libraries can be found under the \textbf{filesystem} namespace. + +\begin{outline} +\1\textbf{open}(driveLetter: String, path: String, operationMode: String) +\\Opens a file on the specified drive. + \2Operation Mode: \textbf{R} for read, \textbf{W} for overwrite, \textbf{A} for append +\1\textbf{readAll}(driveLetter: String) +\\Reads entire content of the file and return it as a string. +\1\textbf{write}(driveLetter: String, bytes: String) +\\Writes bytes onto the file opened for specified drive. +\1\textbf{isDirectory}(driveLetter: String) +\\Returns true if the file opened for the drive is a directory. +\1\textbf{mkDir}(driveLetter: String) +\\Creates a directory of opened path for the drive. Usage: +\\\code{filesystem.open("A", "path/to/nonexisting/directory", "W"); filesystem.mkDir("A")} +\1\textbf{touch}(driveLetter: String) +\\Updates a last-modified date of the opened file. If file does not exist, creates one. +\1\textbf{mkFile}(driveLetter: String) +\\Creates a file of opened path for the drive. Usage: +\\\code{filesystem.open("A", "path/to/nonexisting/file", "W"); filesystem.mkFile("A")} +\end{outline} + + +\section{The Graphics Library} + +\index{gl (DOS)}Functions in the graphics libraries can be found under the \textbf{gl} namespace.