Started a Developer's Guide

docs/foenixmcp.tex

@@ -0,0 +1,185 @@
+\documentclass{report}
+\usepackage[T1]{fontenc}
+\usepackage{ccfonts}
+\begin{document}
+\newcommand{\MCP}{{\sc Foenix/MCP}}
+\newcommand{\param}[1]{{\tt #1}}
+\newcommand{\name}[1]{{\tt #1}}
+
+\title{{\MCP} a Simple, Portable Operating System for the Foenix Line of Computers}
+\author{Peter J. Weingartner}
+\date{19 September, 2021}
+\maketitle
+
+\chapter{Overview}
+
+\section{Copyrights}
+
+\chapter{Command Line Utility}
+
+\section{Paths}
+
+\section{External Commands}
+
+\section{Internal Commands}
+
+\subsection{Numbers}
+
+Several internal commands use numbers as arguments.
+These numbers can be specified in one of three ways: decimal, binary, or hexadecimal.
+A decimal number is written just the usual numerals between \param{0} and \param{9}.
+A binary number must be prefixed with either \param{\%} or \param{0b}.
+A hexadecimal number must be prefixed with either \param{\$} or \param{0x}.
+
+\subsection{File System Commands}
+
+\subsection{Memory Commands}
+
+\subsection{Graphics Commands}
+
+\chapter{Devices}
+
+There are two main ways of supporting devices in {\MCP}: channel devices, and block devices.
+Bytes may be written to or read from a channel, but the bytes are always in order.
+Every channel has a ``cursor'', which marks where the next byte to read or write is.
+Some channels may support the ability to move the cursor, but some will not have that ability.
+Examples of channels include the text screens, the keyboard, the serial port, and files open for
+reading or writing.
+
+Block devices, on the other hand support reading or writing an entire block of bytes at a time.
+Every block has an ``address'' on the device, and blocks may be read or written in any order
+and location by specifying the address desired. Examples of block devices include a hard drive,
+SD card, or floppy drive.
+
+\section{Channels and Channel Devices}
+
+{\MCP} supports several channel devices, including: main console screen, secondary console screen
+(Channel B or the EVID card), the COM ports on the computer, MIDI ports (if available), and
+parallel printer port (if available):
+
+\begin{table}
+    \begin{center}
+        \begin{tabular}{|l|l|l| } \hline
+            Number & Device & Name \\ \hline
+            0 & Console (Channel A) & \param{@CONA:} \\ \hline
+            1 & Channel B or EVID & \param{@CONB:} \\ \hline
+            2 & Serial Port \#1 & \param{@COM1:} \\ \hline
+            3 & Serial Port \#2 & \param{@COM2:} \\ \hline
+            4 & Parallel Port & \param{@LPT1:} \\ \hline
+            5 & MIDI Port & \param{@MIDI:} \\ \hline
+        \end{tabular}
+    \end{center}
+    \caption{Built in channel devices}
+    \label{cdev:list}
+\end{table}
+
+Channel devices support several operations. User programs will not generally access channel devices
+directly, but will instead access them through an open channel. Each channel will be referenced by
+its number. By default, the operating system will have already created a channel for each channel
+device present on the system, and the channel number will match that of its device. Another source
+of channels is to open a file (see below).
+
+\begin{itemize}
+    \item Read---Read a number of bytes from the channel.
+
+    \item Read Byte---Read a single byte from the channel.
+
+    \item Read Line---Read a line of text from the channel (delimited by a newline character).
+
+    \item Write---Write a number of bytes to the channel device.
+
+    \item Write Byte---Write a single byte to the channel.
+
+    \item Flush---Ensure that any pending writes are completed on the device.
+
+    \item Seek---Move the channel cursor to a different position in the channel. This may not be supported by all types of channels.
+
+    \item Status---Return the status of the block device.
+
+    \item IOCTRL---Set options for the block device. Some options will be common, but others will be device-dependent.
+\end{itemize}
+
+\section{Block Devices}
+
+{\MCP} supports three block devices: SD cards, hard drives on the IDE (PATA) interface, and floppy drives.
+
+\begin{table}
+    \begin{center}
+        \begin{tabular}{|l|l|l| } \hline
+            Number & Device & Name \\ \hline
+            0 & SD Card & \param{@S:} \\ \hline
+            1 & Floppy Drive & \param{@F:} \\ \hline
+            2 & Hard Drive & \param{@H:} \\ \hline
+        \end{tabular}
+    \end{center}
+    \caption{Built in block devices}
+    \label{bdev:list}
+\end{table}
+
+Block devices support several operations:
+
+\begin{itemize}
+    \item Read---Read a block of data from the block device.
+
+    \item Write---Write a block of data to the block device.
+
+    \item Flush---Ensure that any pending writes are completed on the device.
+
+    \item Status---Return the status of the block device.
+
+    \item IOCTRL---Set options for the block device. Some options will be common, but others will be device-dependent.
+\end{itemize}
+
+\section{Files}
+
+{\MCP} provides for file access on block devices. The operations supported for files include:
+
+\begin{itemize}
+    \item Open---Create a channel (with a unique channel number) which can be used to read, write, or append a file.
+
+    \item Close---Shut down access to a previously open file, given its channel number. Files open for writing or appending will commit any pending write operations.
+
+    \item Delete---Remove a file from its block device.
+
+    \item Rename---Change the name of a file.
+
+    \item Copy---Make a copy of a file.
+\end{itemize}
+
+In addition to files, {\MCP} supports directory access:
+
+\begin{itemize}
+    \item OpenDir---Open a directory to list out the files present.
+
+    \item CloseDir---Close a previously open directory.
+
+    \item ReadDir---Read an entry out of an open directory.
+
+    \item FindFirst---Find the first entry in a directory that matches a search pattern.
+
+    \item FindNext---Find the next entry in a directory that matches a search pattern.
+\end{itemize}
+
+\chapter{System Calls}
+
+\section{Channel Calls}
+
+\section{Block Calls}
+
+\section{File System Calls}
+
+\section{Miscellaneous Calls}
+
+\chapter{Keyboard Operations}
+
+\section{Scancodes}
+
+\section{Translation Tables}
+
+\chapter{Implementing Device Drivers}
+
+\section{Channel Device Drivers}
+
+\section{Block Device Drivers}
+
+\end{document}

src/foenixmcp.c

@@ -421,7 +421,7 @@ int main(int argc, char * argv[]) {
     // try_mo_scancodes(0);
     // try_bdev_getput(0, BDEV_SDC);
 
-    cli_repl(0);
+    cli_repl(1);
 
     DEBUG("Stopping.");
 

src/foenixmcp.s68

@@ -101,8 +101,8 @@ S224010B20436F756C64206E6F7420777269746520626C6F636B2E0A00436F756C64206E6FA5
 S224010B4074207265616420626C6F636B2E0A0000426C6F636B20646964206E6F7420766554
 S224010B60726966792E0A00004244455620726561642F777269746520737563636573732EFF
 S224010B800A004E716100F8C2487A004642A76100F720487A004C487800016100F714487A05
-S224010BA0FBBC42A74EB900010F4842A74EB900010EF842A74EB90001A454487A00344EB953
-S224010BC000010D004FEF002460FE70004E754E7154657874204368616E6E656C20410A0066
+S224010BA0FBBC42A74EB900010F4842A74EB900010EF8487800014EB90001A454487A003284
+S224010BC04EB900010D004FEF002460FE70004E7554657874204368616E6E656C20410A001E
 S224010BE054657874204368616E6E656C20420A0053746F7070696E672E004E714053000031
 S224010C0040460000404800004CEF000300044A816B0A4A806B12616220014E7544814A80C1
 S224010C206B10615620014E754480614E448120014E7544806144448120014E754CEF00032C

src/mapfile

@@ -752,9 +752,9 @@ Symbols of text:
   0x00010b50 l143: local reloc, size 0
   0x00010b68 l144: local reloc, size 0
   0x00010b84 _main: global reloc, size 0
-  0x00010bc8 l153: local reloc, size 0
-  0x00010bca l155: local reloc, size 0
-  0x00010bcc l148: local reloc, size 0
+  0x00010bca l153: local reloc, size 0
+  0x00010bcc l155: local reloc, size 0
+  0x00010bce l148: local reloc, size 0
   0x00010bd0 l150: local reloc, size 0
   0x00010be0 l151: local reloc, size 0
   0x00010bf0 l152: local reloc, size 0