curioustorvald/tsvm
1
0
Fork 0
mirror of https://github.com/curioustorvald/tsvm.git synced 2026-03-07 11:51:49 +09:00
Code Issues Packages Projects Releases Wiki Activity

doc update

Browse Source
This commit is contained in:
minjaesong
2022-08-27 01:49:57 +09:00
parent 79f4584dd4
commit e91fac4fb5
8 changed files with 180 additions and 90 deletions
Download Patch File Download Diff File Expand all files Collapse all files

55
doc/implementation.tex
View File

@@ -12,27 +12,40 @@
There are three memories on the system: Hardware Memory (8 MB), Scratchpad Memory (up to 8 MB) and Program Memory (infinite!)
Your Javascript program is stored into the Program Memory, and since its capacity is limitless, you can put large graphics directly into your Javascript source code, but Program Memory is the slowest of all three memories. For faster graphics, you need to store them on the Scratchpad Memory and DMA-Copy them to the graphics adapter.
Your Javascript program is stored into the Program Memory, and since its capacity is limitless, you can put a large graphics directly into your Javascript source code, but the Program Memory is the slowest of all three memories. For faster graphics, you need to store them onto the Scratchpad Memory then DMA-Copy them to the graphics adapter.
\section{Built-in Commands}
\subsection{Javascript Extensions}
\index{js extensions}\thismachine\ provides the extra functions for your convenience.
\begin{outline}
\1Array.\textbf{head}() --- returns the first element of the array.
\1Array.\textbf{last}() --- returns the last element of the array.
\1Array.\textbf{tail}() --- returns the subarray that omits the \emph{head} element.
\1Array.\textbf{init}() --- returns the subarray that omits the \emph{last} element.
\1Array.\textbf{sum}(selector) --- returns the sum of the elements of the array. Selector can be optionally defined to indicate how the value must be transformed to obtain the sum.
\1Array.\textbf{max}(selector) --- returns the maximum among the elements of the array. Selector can be optionally defined to indicate how the value must be transformed to obtain the max.
\end{outline}
\subsection{Standard Input and Output}
\index{stdio (library)}These are standard input/output functions:
\begin{outline}
\1\textbf{print}(string) --- prints a string without new line.
\1\textbf{print}(string) --- prints a string without a new line.
\1\textbf{println}(string) --- prints a string with a new line.
\1\textbf{printerr}(string) --- prints a string to error output without new line.
\1\textbf{printerr}(string) --- prints a string to error output without a new line.
\1\textbf{printerrln}(string) --- prints a string to error output with a new line.
\1\textbf{read}() --- reads a string from keyboard. Hit Return to finish reading.
\1\textbf{read}() --- reads a string from the keyboard. Hit the Return to finish reading.
\end{outline}
\subsection{Console}
\index{console (library)}Console library contains functions for screen text manipulation.
\index{console (library)}Console library contains the functions for screen text manipulation.
\namespaceis{Console}{con}
@@ -43,12 +56,12 @@ Your Javascript program is stored into the Program Memory, and since its capacit
\subsection{System}
\index{system (library)}System library has functions to get the status of the system.
\index{system (library)}System library has the functions to get the status of the system.
\namespaceis{System}{system}
\begin{outline}
\1\textbf{maxmem}() --- returns size of the Scratchpad Memory in bytes.
\1\textbf{maxmem}() --- returns the size of the Scratchpad Memory in bytes.
\end{outline}
@@ -66,7 +79,7 @@ Your Javascript program is stored into the Program Memory, and since its capacit
\subsection{Base64}
\index{base64 (library)}Base64 allows encoding of binary data into ASCII-strings and vice-versa.
\index{base64 (library)}Base64 allows encoding of the binary data into the ASCII-strings and vice-versa.
\namespaceis{Base64}{base64}
@@ -94,34 +107,36 @@ Some pheripherals such as disk drives are connected through the ``Serial Communi
Unlike the name suggests, Serial Communication is not at all \emph{serial}; it's more like a \emph{block communication}.
\section{Concept of Block Communication}
\section{Concept of the Block Communication}
\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.
\index{block communication}As long as the Sender and the Receiver are somehow connected and being recognised, the communication channel between two devices are open and available. There are two blocks per port: the send-block and the 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 the 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 the 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.
When the read/write operation 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}
\index{com (library)}portNo is a number of the port in 0--3, 0 being the first port.
\namespaceis{Com}{com}
\begin{outline}
\1\textbf{sendMessage}(portNo: Int, message: String)
\\Sends message to the port and returns status code the other machine emits.
\1\textbf{fetchResponse}(portNo: Int)
\1\textbf{fetchResponse}(portNo: Int): String
\\Fetches the message composed by other device to this machine.
\1\textbf{sendMessageGetBytes}(portNo: Int, message: String)
\1\textbf{sendMessageGetBytes}(portNo: Int, message: String): String
\\Sends message, waits for responce, then returns the received message.
\1\textbf{waitUntilReady}(portNo: Int)
\\Blocks the program until the other device is ready.
\1\textbf{pullMessage}(portNo: Int)
\1\textbf{pullMessage}(portNo: Int): String
\\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)
\1\textbf{getStatusCode}(portNo: Int): Int
\\Returns the status code of the other device.
\1\textbf{getDeviceStatus}(portNo: Int)
\1\textbf{getDeviceStatus}(portNo: Int): \{code: Int, message: String\}
\\Returns the status message of the other device. Different types of devices may have different messages.
\1\textbf{areYouThere}(portNo: Int)
\1\textbf{areYouThere}(portNo: Int): Boolean
\\Returns true if there is other device connected and is working.
\end{outline}
@@ -130,7 +145,7 @@ While read/write is being processed, each side emits ``busy'' flag indicating th
\begin{lstlisting}
com.sendMessage(0, "DEVRST\x17") // resets the disk drive
com.sendMessage(0, 'OPENR"my-awesome.txt",1') // tells the disk drive to open a file named 'my-awesome.txt' from drive number 1 for reading
com.sendMessage(0, 'OPENR"my-awesome.txt",1') // tells the disk drive to open a file named 'my-awesome.txt' from the drive number 1 for reading
let status = com.getStatusCode(0)
if (0 == status){
com.sendMessage(0, "READ") // tells the disk drive that I'm about to read the file just opened
@@ -149,7 +164,7 @@ if (0 == status){
\begin{lstlisting}
com.sendMessage(0, "DEVRST\x17") // resets the disk drive
com.sendMessage(0, 'OPENW"my-awesomer.txt",1') // tells the disk drive to open a file named 'my-awesomer.txt' from drive number 1 for writing
com.sendMessage(0, 'OPENW"my-awesomer.txt",1') // tells the disk drive to open a file named 'my-awesomer.txt' from the drive number 1 for writing
let status = com.getStatusCode(0)
if (0 == status){
com.sendMessage(0, "WRITE1234") // tells the disk drive that I'm about to write to the file just opened. 1234 is a size of the text to write
@@ -186,7 +201,7 @@ Address & RW & Description \\
\subsection{Transfer Status Bits and Transfer Control}
The com-port will behave differently if you're writing or reading on the address. In other words, you cannot read what you have just wrote because reading will put the port in different state.
The com-port will behave differently if you're writing to or reading from the address. In other words, you cannot read what you have just wrote because the reading will put the port in a different state.
\begin{figure}[h]
\begin{center}

35
doc/tsvmman.idx
View File

@@ -1,22 +1,25 @@
\indexentry{stdio (library)|hyperpage}{7}
\indexentry{js extensions|hyperpage}{7}
\indexentry{stdio (library)|hyperpage}{8}
\indexentry{console (library)|hyperpage}{8}
\indexentry{con (library)|hyperpage}{8}
\indexentry{system (library)|hyperpage}{8}
\indexentry{system (library)|hyperpage}{8}
\indexentry{gzip (library)|hyperpage}{8}
\indexentry{gzip (library)|hyperpage}{8}
\indexentry{base64 (library)|hyperpage}{8}
\indexentry{base64 (library)|hyperpage}{8}
\indexentry{sys (library)|hyperpage}{8}
\indexentry{block communication|hyperpage}{9}
\indexentry{com (library)|hyperpage}{9}
\indexentry{MMIO-com|hyperpage}{11}
\indexentry{keycodes|hyperpage}{13}
\indexentry{code page|hyperpage}{15}
\indexentry{colour palette|hyperpage}{17}
\indexentry{MMIO-graphics|hyperpage}{19}
\indexentry{boot process|hyperpage}{22}
\indexentry{filesystem (DOS)|hyperpage}{24}
\indexentry{filesystem (DOS)|hyperpage}{24}
\indexentry{input (DOS)|hyperpage}{25}
\indexentry{gl (DOS)|hyperpage}{25}
\indexentry{base64 (library)|hyperpage}{9}
\indexentry{base64 (library)|hyperpage}{9}
\indexentry{sys (library)|hyperpage}{9}
\indexentry{block communication|hyperpage}{10}
\indexentry{com (library)|hyperpage}{10}
\indexentry{com (library)|hyperpage}{10}
\indexentry{MMIO-com|hyperpage}{12}
\indexentry{keycodes|hyperpage}{14}
\indexentry{code page|hyperpage}{16}
\indexentry{colour palette|hyperpage}{18}
\indexentry{MMIO-graphics|hyperpage}{20}
\indexentry{boot process|hyperpage}{23}
\indexentry{filesystem (DOS)|hyperpage}{25}
\indexentry{file descriptor (DOS)|hyperpage}{25}
\indexentry{device file|hyperpage}{27}
\indexentry{input (DOS)|hyperpage}{29}
\indexentry{gl (DOS)|hyperpage}{29}

8
doc/tsvmman.ilg
View File

@@ -1,6 +1,6 @@
This is makeindex, version 2.15 [TeX Live 2021] (kpathsea + Thai support).
Scanning input file tsvmman.idx....done (22 entries accepted, 0 rejected).
Sorting entries....done (95 comparisons).
Generating output file tsvmman.ind....done (43 lines written, 0 warnings).
This is makeindex, version 2.16 [TeX Live 2022] (kpathsea + Thai support).
Scanning input file tsvmman.idx....done (25 entries accepted, 0 rejected).
Sorting entries....done (112 comparisons).
Generating output file tsvmman.ind....done (52 lines written, 0 warnings).
Output written in tsvmman.ind.
Transcript written in tsvmman.ilg.

37
doc/tsvmman.ind
View File

@@ -1,43 +1,52 @@
\begin{theindex}
\item base64 (library), \hyperpage{8}
\item block communication, \hyperpage{9}
\item boot process, \hyperpage{22}
\item base64 (library), \hyperpage{9}
\item block communication, \hyperpage{10}
\item boot process, \hyperpage{23}
\indexspace
\item code page, \hyperpage{15}
\item colour palette, \hyperpage{17}
\item com (library), \hyperpage{9}
\item code page, \hyperpage{16}
\item colour palette, \hyperpage{18}
\item com (library), \hyperpage{10}
\item con (library), \hyperpage{8}
\item console (library), \hyperpage{8}
\indexspace
\item filesystem (DOS), \hyperpage{24}
\item device file, \hyperpage{27}
\indexspace
\item gl (DOS), \hyperpage{25}
\item file descriptor (DOS), \hyperpage{25}
\item filesystem (DOS), \hyperpage{25}
\indexspace
\item gl (DOS), \hyperpage{29}
\item gzip (library), \hyperpage{8}
\indexspace
\item input (DOS), \hyperpage{25}
\item input (DOS), \hyperpage{29}
\indexspace
\item keycodes, \hyperpage{13}
\item js extensions, \hyperpage{7}
\indexspace
\item MMIO-com, \hyperpage{11}
\item MMIO-graphics, \hyperpage{19}
\item keycodes, \hyperpage{14}
\indexspace
\item stdio (library), \hyperpage{7}
\item sys (library), \hyperpage{8}
\item MMIO-com, \hyperpage{12}
\item MMIO-graphics, \hyperpage{20}
\indexspace
\item stdio (library), \hyperpage{8}
\item sys (library), \hyperpage{9}
\item system (library), \hyperpage{8}
\end{theindex}

4
doc/tsvmman.tex
View File

@@ -69,8 +69,8 @@
\hyphenation{ECMA-script}
\hyphenation{name-space}
\newcommand{\namespaceis}[2]{\index{#2 (library)}Functions in the #1 library can be found under the \textbf{#2} namespace.}
\newcommand{\dosnamespaceis}[2]{\index{#2 (DOS)}Functions in the \thedos\ #1 library can be found under the \textbf{#2} namespace.}
\newcommand{\namespaceis}[2]{\index{#2 (library)}The functions in the #1 library can be found under the \textbf{#2} namespace.}
\newcommand{\dosnamespaceis}[2]{\index{#2 (DOS)}The functions in the \thedos\ #1 library can be found under the \textbf{#2} namespace.}
\newcommand\forceindent{\hskip1.5em}

118
doc/tvdos.tex
View File

@@ -33,42 +33,104 @@ Variables can be set or changed using \textbf{SET} commands.
\chapter{DOS Commands}
\chapter{DOS Libraries}
\chapter{File I/O}
\index{filesystem (DOS)}In \thedos, drives are assigned with a drive letter, and the drive currently booted on is always drive \textbf{A}.
\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 File Descriptor}
\index{file descriptor (DOS)}A file is virtualised through the \emph{file descriptor} which provides the functions to manipulate the file. Do note that when a file descriptor is created, the file is not yet opened by the drive.
\section{The Filesystem Library}
To create a file descriptor, use the provided function \code{files.open(fullpath)}. \code{fullpath} is a fully qualified path of the file that includes the drive letter.
\dosnamespaceis{Filesystem}{filesystem}
\section{Manipulating a File}
A file has folliwing properties and can be manipulated using following functions:
Properties:
\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{readAllBytes}(driveLetter: String)
\\Reads entire content of the file and return it as a array of bytes.
\1\textbf{getFileLen}(driveLetter: String)
\\Returns a size of the file currently opened.
\1\textbf{write}(driveLetter: String, bytes: String)
\\Writes bytes onto the file opened for specified drive.
\1\textbf{writeBytes}(driveLetter: String, bytes: ByteArray)
\\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")}
\1\textbf{size}: Int
\\Returns a size of the file in bytes.
\1\textbf{path}: String
\\Returns a path (NOT including the drive letter) of the file. Paths are separated using reverse solidus.
\1\textbf{fullpath}: String
\\Returns a fully qualified path (including the drive letter) of the file. Paths are separated using reverse solidus.
\1\textbf{driverID}: String
\\Returns a filesystem driver ID associated with the file.
\1\textbf{driver}: [Object object]
\\Returns a filesystem driver (a Javascript object) for the file.
\1\textbf{isDirectory}: Boolean
\\Returns true if the path is a directory.
\1\textbf{name}: String
\\Returns the name part of the file's path.
\1\textbf{parentPath}: String
\\Returns a parent path of the file.
\1\textbf{exists}: Boolean
\\Returns true if the file exists on the device.
\end{outline}
Functions:
\begin{outline}
\1\textbf{pread}(pointer: Int, count: Int, offset: Int)
\\Reads the file bytewise and puts it to the memory starting from the \code{pointer}.
\2\code{count}: how many bytes to read
\2\code{offset}: when reading a file, how many bytes to skip initially
\1\textbf{bread}(): Array
\\Reads the file bytewise and returns the content in Javascript array.
\1\textbf{sread}(): String
\\Reads the file textwise and returns the content in Javascript string.
\1\textbf{pwrite}(pointer: Int, count: Int, offset: Int)
\\Writes the bytes stored in the memory starting from the \code{pointer} to file.
\2\code{count}: how many bytes to write
\2\code{offset}: when writing to the file, how many bytes on the file to skip before writing a first byte.
\1\textbf{bwrite}(bytes: UintArray)
\\Writes the bytes to the file.
\1\textbf{swrite}(string: String)
\\Writes the string to the file.
\1\textbf{flush}()
\\Flush the contents on the write buffer to the file immediately. Will do nothing if there is no write buffer implemented --- a write operation will always be performed imemdiately in such cases.
\1\textbf{close}()
\\Tells the underlying device (usually a disk drive) to close a file. When dealing with multiple files on a single disk drive (of which can only have a single active---or opened---file), the underlying filesystem driver will automatically swap the files around, so this function is normally unused.
\1\textbf{list}(): Array or undefined
\\Lists files inside of the directory. If the path is indeed a directory, an array of file descriptors will be returned; \code{undefined} otherwise.
\1\textbf{touch}(): Boolean
\\Updates the file's access time if the file exists; a new file will be created otherwise. Returns true if successful.
\1\textbf{mkDir}(): Boolean
\\Creates a directory to the path. Returns true if successful.
\1\textbf{mkFile}(): Boolean
\\Creates a new file to the path. Returns true if successful.
\1\textbf{remove}(): Boolean
\\Removes a file. Returns true if successful.
\end{outline}
\section{The Device Files}
\index{device file}Some devices are also virtualised through the file descriptor, and they are given a special path. (their fullpath does not contain a drive letter)
\begin{outline}
\1\textbf{RND} --- returns random bytes upon reading
\2\textbf{pread}: returns the specified number of random bytes
\1\textbf{NUL} --- returns EOF upon reading
\2\textbf{pread}: returns the specified number of EOFs
\2\textbf{bread}: returns an empty array
\2\textbf{sread}: returns an empty string
\1\textbf{ZERO} --- returns zero upon reading
\2\textbf{pread}: returns the specified number of zeros
\1\textbf{CON} --- manipulates the screen text buffer, disregarding the colours
\2\textbf{pread}: reads the texts as bytes.
\2\textbf{bread}: reads the texts as bytes.
\2\textbf{sread}: reads the texts as a string.
\2\textbf{pwrite}: writes the bytes from the given pointer.
\2\textbf{bwrite}: identical to \code{print()} except the given byte array will be casted to string.
\2\textbf{swrite}: identical to \code{print()}.
\1\textbf{FBIPF} --- decodes IPF-formatted image to the framebuffer. Use the \emph{Graphics} library for the encoding.
\2\textbf{pwrite, bwrite} --- decodes the given IPF binary data. \code{pwrite} offsets and counts are ignored.
\end{outline}
\chapter{DOS Libraries}
\section{The Input Library}