                        ===================
                        BOTBIOS version 1.0
                        ===================

                             Contents
                             ========

1 - BOTBIOS 
2 - BOTBIOS Support for Intel HEX file transfer 
3 - BOTBIOS Supported Interrupts 
4 - BOTBIOS System Resource management 
5 - NMIT-0025 Board Preparation necessary for BOTBIOS 


1 - BOTBIOS 
===========

BOTBIOS, short for Robotics Basic Input/Output System, is intended to
provide basic, PC like support for programs written with PC
programming tools and running on an x86 single board computer. A
fundamental goal of BOTBIOS is to keep it as simple as possible. It
is not meant to be a complete implementation of a PC. It does permit
extensions to be installed.

BOTBIOS is in its early stages of development. It is currently
running on a board available from New Micros, Inc (their NMIT-0025)
which uses the NEC V25 processor, a clone of the Intel 8088 intended
for embedded system use. BOTBIOS will be ported to the Intel '186
series and probably the 386ex. Currently there is a minimum number of
supported interrupts providing this PC like support. Other system
resources are managed by extensions to the software interrupt
structure. And there is some preparation necessary on the NMIT-0025
board.

Console I/O, which on a PC typically uses INT 10h and INT 16h, is
supported and directed over a serial port of the single board
computer. To a user sitting at a terminal or terminal program
connected to this serial port, a prompt is provided that appears
similar to a PC. This is offered as the development environment for
the board. (Note that while this prompt appears similar to a PC, it
is not intended to be used as a general purpose computer.)

BOTBIOS has what can be considered a file system. It's purpose is not
to manage a disk, but instead to manage a collection of files in
memory, typically in EPROM. When looking for these files, BOTBIOS
will scan on 4k boundaries for a marker that indicates a collection
of files. On finding this marker, information in a header indicates
the files contained. These collections of files contain one or more
PC COM files. The ROMMAKER utility puts these COM files together and
adds the header information that is used by BOTBIOS.

BOTBIOS occupies the upper portion of the EPROM which is located at
the top of the processors address space such that when the processor
is reset, BOTBIOS gains control. The remainder of the BOTBIOS EPROM
contains one of these collections of files. BOTBIOS can handle
multiple collections of files which would permit, for instance, a
collection of rarely changing utilities to be placed in the BOTBIOS
EPROM and a second EPROM that contains user developed programs that,
for instance, control a robot in various circumstances or contests.

An example of one of these rarely changing utilities is a program
that lists the files found in the file system. Typing the name of
this utility, DIR, at the BOTBIOS command prompt will cause the DIR
program to be loaded and executed. And of course the DIR program
simply scans and provides a list of all programs in the current
BOTBIOS file system.

These collections of files are not restricted to EPROM - they can be
downloaded to RAM using the Intel HEX transfer capability, permitting
program development and testing without having to place the programs
in an EPROM.

The BOTBIOS command prompt accepts transfers of Intel HEX files as a
method to download programs into the board's memory. To do this
transfer use the ASCII transfer protocol of the terminal program and
specify the name of the HEX file. When the download begins BOTBIOS
realizes it is receiving the HEX records of an Intel HEX file and
stores the data as such.

BOTBIOS supports the concept of a terminate-and-stay-resident
program. In its simplest sense this just means that a program is
loaded in memory, potentially installs one or more interrupt
handlers, and exits. The difference is that the memory used by the
program is not released - it remains resident - making the interrupt
handler(s) available for other programs to use.

The idea here is to permit extensions, or what might be called device
drivers, to be installed. A servo motor driver could be written and
installed. Now any number of programs can be run that use the servo
motor. This prevents every program from having to contain servo motor
driver code and enables a place for maintaining that source (you
don't have to touch every file if you update the servo motor driver
code). This also permits BOTBIOS to remain simple. And users can
distribute the drivers they have written allowing others to take
advantage of their work.


2 - BOTBIOS Support for Intel HEX file transfer 
===============================================

The Intel HEX file is a text file encoding of, typically, a binary
file. It is generally used as a format for transferring binary files
to a device such as an EPROM programmer. BOTBIOS also uses it.

BOTBIOS supports the transfer of Intel HEX files at the BOTBIOS
command prompt. A transfer is initiated by using a communications
program's ASCII transfer capability. BOTBIOS will recognize it is
receiving an Intel HEX file and store the transferred data as such.
This provides a convenient method of testing a program without having
to burn it into an EPROM.

The utility IHEX.EXE is included with the BOTBIOS files. This utility
creates an Intel HEX file version of an existing file. The file to be
converted is provided on the command line of IHEX, along with some
additional, optional, command line switches.

These switches currently include:

- /se[gment] hhhh - specify in hexadecimal the segment for the
transfer to write to, where hhhh represents the hexadecimal address.

- /of[fset] hhhh - specify in hexadecimal the offset. 

The default behavior in BOTBIOS for Intel HEX transfers it to use the
beginning of free memory for the segment to write to. The assumption
is that a PC COM file is being transferred and therefore BOTBIOS
assumes the offset to be 100h (the entry point of a PC COM file).

So to create an Intel HEX file for TEST.COM the IHEX command line
would be:

- ihex test.com 

and TEST.HEX would be created. On transferring this to BOTBIOS, this
file would be written to 007C:0100, assuming for the moment that the
free memory begins at segment 007C. This file can then be executed by
setting the dispatch value (port 0, bits 3-0) to zero (0000) and
hitting the reset switch.

The /segment switch is used to change the target segment and would,
for instance, be used to specify the segment a transfer should write
to when transferring an FTD file system file. When the /segment
switch is used it is assumed that the file being transferred is not a
PC COM file and BOTBIOS reverts the offset to zero. Generally this is
the desired behavior but the /offset switch can be used change that,
although the /offset switch is usually omitted.

To create an Intel HEX file for MYFILES.BIN, a collection of COM
files put together with ROMMAKER, the command line would be:

- ihex /se 1800 myfiles.bin 

and MYFILES.HEX would be created. On transferring this to BOTBIOS,
this file would be written to 1800:0000. This is at a 4k boundary so
BOTBIOS's scan for files would find it and make them available for
execution. Files from this download can be executed by either typing
the name at the BOTBIOS command prompt or by setting the dispatch
value (port 0, bits 3-0) to the number (N) of the file. The number N
is just the number, in order, of the file from the beginning of the
list of all files found by BOTBIOS (use DIR and count them).


3 - BOTBIOS Supported Interrupts 
================================

Software interrupts currently supported by BOTBIOS version 0.86

* denotes only a partial PC implementation
# denotes a BOTBIOS extension

int 00h* only to report integer-divide-by-zero

int 03h# only to report existence of the breakpoint interrupt

int 10h*

- func 02h* set cursor position. This function is ignored and simply
returns.

- func 03h* get cursor position. This function is ignored and simply
returns.

- func 09h* put multiple characters. This function prints to the
console multiple characters where the character is contained in the
AL register and the count is contained in the CX register.
Information about the display page (BH) and attributes/color (BL) is
ignored.

- func 0Ah* put multiple character. This function is effectively the
same as function 09h.

- func 0Eh* put character. This function prints the character
contained in register AL to the console. Information about the
display page (BH) and color (BL) is ignored.

- func 0Fh* get display mode. This function is ignored and simply
returns.

- func 20h# put ASCIIZ w/CRLF. This function prints to the console
the null terminated string pointed to by DS:DX followed by a carriage
return and a line feed, similar to the C puts() function. This is a
BOTBIOS extension.

- func 21h# put ASCIIZ. This function prints to the console the null
terminated string pointed to by DS:DX. This is a BOTBIOS extension. 

- func 22h# put decimal digit. This function prints to the console
the ASCII equivalent of the lower four bits of register AL (range
0-9). This is a BOTBIOS extension. 

- func 23h# put decimal short with leading zeros for two places. This
function prints to the console the ASCII unsigned decimal equivalent
of the value in register AL preserving leading zeros for two places.
This is a BOTBIOS extension. 

- func 24h# put decimal int. This function prints to the console the
ASCII unsigned decimal equivalent of the value in register BX with
leading zeros suppressed. This is a BOTBIOS extension. 

- func 25h# put hexadecimal short with leading zeros. This function
prints to the console the two digit hexadecimal ASCII equivalent of
the value in register AL. This is a BOTBIOS extension. 

- func 26h# put hexadecimal int with leading zeros. This function
prints to the console the four digit hexadecimal ASCII equivalent of
the value in register BX. This is a BOTBIOS extension. 

- func 27h# put hexadecimal long pointer with leading zeros. This
function prints to the console the eight digit hexadecimal ASCII
equivalent of the value in register DX:BX in the 0000:0000 format of
a far address. This is a BOTBIOS extension. 

int 16h*

- func 00h* get keyboard character. This functions returns in
register AL a character from the console. Note that the scan code is
not made available in register AH as does a PC.

- func 01h get keyboard status. This function returns with the zero
flag clear and the character in register AL if a character is waiting
to be read from the console (the scan code is not returned in
register AH). The character is not removed from the buffer; for this
use function 00h. If no character is waiting to be read, the function
returns with the zero flag set. 

int 20h* terminate. 

- This function is used by a program to terminate, returning control
to BOTBIOS with BOTBIOS freeing the memory allocated to load the
program and freeing memory allocated by the program. BOTBIOS does not
support the concept of a return code. This is the same as interrupt
21h func 4Ch, which is preferred, and as interrupt 21h function 0. 

int 21h*

- func 00h* terminate. This function is used by a program to
terminate, returning control to BOTBIOS with BOTBIOS freeing the
memory allocated to load the program and freeing memory allocated by
the program. This is the same as interrupt 21h func 4Ch, which is
preferred.

- func 01h get character

- func 02h put character

- func 09h put $ terminated string

- func 0Ch* alternate functions

- func 25h set interrupt vector

- func 31h* terminate and stay resident. This function is used by a
program to terminate but to remain resident in memory. The memory
allocated to load the program and lo memory subsequently allocated by
the program determines what memory to reserve rather that the value
in register DX as does a PC. The usefulness with this function is
that a program can install one or more interrupt handlers and then
exit while remaining resident. These interrupt handlers can then be
used by other programs. This forms the basis for the extensibility of
BOTBIOS, what might be called device drivers.

- func 35h get interrupt vector

- func 4Ch* terminate. This is the preferred function to be used by a
program to terminate, returning control to BOTBIOS with BOTBIOS
freeing the memory allocated to load the program and freeing memory
allocated by the program. BOTBIOS does not support the concept of a
return code. 


4 - BOTBIOS System Resource management 
======================================

System resources comprise memory, FTD (read-only,
file-table-descriptor based) file system, and system time base. These
resources are managed by software interrupt 40h functions which are
BOTBIOS extensions.

Interrupt 40h function 0 provides system configuration information.
Interrupt 40h, function 1-Fh are reserved for memory management
routines. Interrupt 40h, functions 10h-1Fh are reserved for FTD file
system support. Interrupt 40h, functions 20h-2Fh are reserved for
system timer functions.

Interrupt 40h system configuration:

- function 0 (getsystemconfig) returns basic system configuration
information. (The majority of this function is yet to be defined.)
Returned in AL in the CPU/board identification. Returned in AH is
BOTBIOS version encoded in binary-coded decimal. Bits 7-4 contain
major and bits 3-0 contain minor version. Returned in BX are the
number of contiguous paragraphs of RAM installed at 0000:0000. The
information in AH and BX is processor independent. The NMI V25 board
returns 10h in AL and the segment of the special function registers
in ES. Unlike most other int 40h functions few registers are
guaranteed to be preserved across this function. Those that are
guaranteed to be preserved are DS, SS, SP, and the flags. 

Interrupt 40h memory management function list:

- function 1 (getmemoryptrs) returns the free memory status. Returned
in BX is the segment address of the low free memory pointer. Returned
in DX is that for the high free memory pointer.

- function 2 (setlomemoryptr) is used to override allocation and set
the low free memory pointer. The new segment address is specified in
BX with the previous value returned in DX. This potentially could be
used to force loading memory at a particular address.

- function 3 (alloclomemory) is used to allocate CX paragraphs in low
memory. Returned in BX is the segment address of the memory
allocated. Returned in DX is the segment address of the new free
memory pointer. A value of zero returned in BX indicates failure to
allocate the requested memory.

- function 4 (sethimemoryptr) is used to override allocation and set
the hi free memory pointer. The new segment address is specified in
BX with the previous value returned in DX.

- function 5 (allochimemory) is used to allocate CX paragraphs in hi
memory. Returned in BX is the segment address of the memory allocated
which also happens to be the hi memory free pointer. Returned in DX
is the previous free pointer value. A value of zero returned in BX
indicates failure to allocate the requested memory. These two
functions (function 3 and 5) grow pointers toward each other in the
lowest contiguous region of RAM. 

Interrupt 40h FTD file system function list:

- function 10h (execFTDfile) is used to load and execute the file
whose name (and FTD header) is pointed to by DX:BX. On exit from the
program, control is returned to the point of call.

- function 11h (loadFTDfile) is used to load the file whose name (and
FTD header) is pointed to by DX:BX and return. The program is not
executed. The memory free pointers are updated to reflect the memory
used. Returned in DX:BX is the entry point of the program. Returned
in CX is the previous free memory pointer which is also the PSP for
the program. Returned in AL is the file header flag byte. (This
function has not been implemented yet.)

- function 12h (initFTDscan) is used to initialize the FTD scan
functions. This clears the scan state. (It also returns in DX the
segment of the system, or BIOS, FTD header.) Initialize the scan
functions by calling function 12h once before beginning a series of
calls to functions 13h and 14h, or function 15h.

- function 13h (scannextFTD) is called to scan, beginning at low
memory, for FTD headers. Returned in BX is the segment address of an
FTD header. Successive calls scan for additional FTD headers up to
and including the system, or BIOS, FTD header. When no more are
found, zero is returned in BX. In all cases, assuming the scan
functions have been initialized, the segment address of the system
FTD header will be returned in DX.

- function 14h (scannextFTDfile) is called to scan for file names in
the FTD most recently found with function 13h. Function 13h must be
called to scan for the FTD used by this function. Returned in DX:BX
is the far pointer to the file name, which is also the pointer to the
header containing information about the file. Subsequent calls scan
for additional file names. When no more files are found in the
current FTD, zero is returned in BX. The segment address of the
current FTD header is always returned in DX, even when no more files
are found.

- function 15h (scannextfile) is similar to function 12h except that
when the no more files for a particular FTD are found, a scan for the
next FTD is automatically performed before scanning for the next
file. Returned in DX:BX is the far pointer to the file name and file
header. When no more files are found, zero is returned in DX:BX. Like
function 12h, DX will contain the segment address of the FTD header
but as successive calls are made, DX will change to reflect the scan
for subsequent FTD headers. 

Always initialize the scan system with a call to function 12h before
a series of calls to 13h-15h. Note that for each initialization with
function 12h, use function 13h, or function 13h in conjunction with
function 14h, or use function 15h. The behavior in mixing function
15h with 13h/14h is undefined.

The logic here is that to find a particular file, use function 15h.
All FTDs will be scanned. If a list of FTDs and their files is
needed, use function 13h in combination with function 14h.

Interrupt 40h timer tick function list:

- function 20h (settimertick) is used to initialize the 32-bit tick
counter to the value stored in DX:BX.

- function 21h (gettimertick) returns in DX:BX the 32-bit tick
counter.

- function 22h (startcountdowntimer) is used to start the count down
timer specified in BX with CX ticks. A currently running count down
timer will be reset to the new value in CX. Specifying a value of
zero in CX stops the count down timer. There are 32 count down timers
available with valid values of 0 - 31. An out of range value is
ignored.

- function 23h (checkcountdowntimer) is used to check the status of
the count down timer specified in BX. Returned in CX is the current
count down timer value. Zero returned in CX indicates the count down
timer has elapsed. An out of range timer value returns zero in CX. 

The system timer tick occurs at 1 ms intervals when BOTBIOS is used
with the New Micros, Inc NMIT-0025 board. An interrupt 41h hook is
available to gain access to the timer tick interrupt. At the end of
its processing, the 1 ms timer tick interrupt calls interrupt 41h,
which by default just returns. 

Using interrupt 21h function 25h, (set interrupt vector) a user
provided interrupt handler can be installed as interrupt 41h to hook
into the 1 ms timer tick interrupt chain. This user installed
interrupt can then be used to provide an interrupt driven time base.
The alternatives are to use interrupt 40h function 21h to provide a
polled time base or interrupt 40h functions 22h/23h to set/check user
specified delays.


5 - NMIT-0025 Board Preparation necessary for BOTBIOS 
=====================================================

The NMIT-0025 board from New Micros, Inc will need preparation to
work with BOTBIOS.

Decide on the method with which the NMIT-0025 is to be powered. This
can be done in one of several ways:

- There is a provision on the board for an LM340T-5 (LM7805) 5-volt
regulator. There are also positions for a full-wave bridge rectifier,
electrolytic filter and ceramic bypass capacitors, and a power
connector. Installing all of these components will allow the board to
be powered from a 6 to 15 volt AC source.

- If only the capacitors and regulator are installed, the board can
be powered from 8 to 20 volt DC source.

- Or simply supply 5-volts from an existing source. 
It is also recommend that an LED and current limiting resister be
installed to show the 5-volt supply is active.
If desired a 3-volt lithium battery can be installed to maintain the
contents in memory if low-power RAM is installed..

The NMIT-0025 will need to have RAM and ROM installed. BOTBIOS
currently requires, at a minimum, a 128k static RAM chip installed in
the LOW MEM position. Avoid pseudo-static RAM. EPROM's 8k and up can
be used in the MID and HIGH MEM positions. 32k (27C256) and 64k
(27C512) probably make the most sense at this point in time.

The NMIT-0025 has three positions for memory. Associated with each of
these positions is a jumper array that is used to configure each
memory position for type and size of memory. There are two choices
here:

- Modify the soldered wire jumpers for the memory to be installed

- Remove the soldered in jumpers and install headers permitting
jumper (shorting) plugs to configure for the memory choices. 
This last choice is definitely preferred, permitting much greater
flexibility in the board's use.

Serial communication components need to be installed. This can be
done in one of two ways.

- The simplest to do involves the use of the MAX-233 based cable
currently in use on Marvin Green's 68HC11 BOTBOARD. (Info can be
found on the Portland Area Robotics Society web page.) This would be
accomplished by installing a 4 pin header and connecting ground,
power, Rx and Tx to the header from various points available on the
PCB. Refer to the schematic and the PCB for this purpose.

- The other is to install, at a minimum, U9 (MAX-232), C3-C6 (10 uf
electrolytic), C19 (0.1 uf ceramic), R2 (10k 1/4 watt resister), and
J10 (a 3 pin header). A cable then needs to be made that plugs onto
J10 and is terminated with a DB9 or DB25 as appropriate for the
individual's needs. (Duplicate with U10, C7-C10, C15, R3, and J11 to
provide a second serial port.) 

If both cases a wire jumper needs to be installed between pins 1 and
2 of the three hole position on the PCB labeled RXD0. (Duplicate on
RXD1 for the second serial port).

A reset switch will need to be installed. Next to the V25 processor
and very near the quartz crystal is a two hole position on the PCB
labeled J3. Run wires from these two holes to a miniature, normally
open push-button switch.

The last step is specific to the needs of BOTBIOS. On startup,
BOTBIOS reads port 0, pins 0-3 to determine how to boot - to run the
command processor or to run one of several user programs in EPROM.

Four resisters (47k) need to connect to the four port 0 pins 0-3 one
each to ground. These individual pins are then left at ground or
pulled to 5-volts to set a 0-15 (0Fh) startup code for BOTBIOS to
read.

The three most obvious methods to use to set the start up code are:

- A 2x4 pin header with jumper (shorting) plugs.

- A four position DIP-switch.

- A rotary hex encoder switch. This is by far the most preferable
since, in the normal use of the board, this startup code will be
changed very often. Electronic Goldmine has three different switches
that can be used:

- G6970 Tiny HEX switch for $1.49 - very small, 6-pin DIP package.

- G7287 HEX switch for $1.00 - medium size (1" sq.) thumbwheel - my
choice, although it takes a bit to figure out how to wire it.

- G6957 DigiSwitch for $2.00 - large, industrial grade thumbwheel. 

At the risk of repeating myself, it is strongly recommend that a hex
encoder switch be used.

It is also recommended that an LED and current limiting resister be
installed between port 2 pin 7 and ground to be used to show a
'heartbeat.' This is a simple method to demonstrate board and program
functionality. Connect the cathode of the LED to ground.

With these modifications in place, the NMIT-0025 is ready for
BOTBIOS. 

Install the BOTBIOS EPROM. Connect the serial port of the NMIT-0025
to your PC and start your favorite communications program,
configuring it for 9600 baud, 8 bits, 1 stop bit, no parity and the
port on your PC you are connected to. On the NMIT-0025, set the hex
switch, or DIP switch, or jumpers on port 0, pins 0-3 such that all
four pins are a logical one (0Fh which runs the BOTBIOS command
processor). 

Apply power to the NMIT-0025 and you will see a prompt from BOTBIOS
with an identification of the BOTBIOS version and the amount of RAM
installed. Type DIR (one of the utilities in BOTBIOS) to see a list
of files currently in BOTBIOS memory.


Bill Bailey
16 May 96
