FoenixMCP/docs/foenixmcp.tex

\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}