-*- Text -*-
   This is the file .../info/BIOS-API.nfo, which contains info
about the Interface between the BIOS and MOOSE for i386 implementation.


File: BIOS-API.nfo	Node: Top	Up:(MOOSE.nfo)

* Menu:

About the BIOS API:
* Intro::			What is the BIOS API ?
* Bootstrapping::		Getting out of the ``real (mode)'' world.
* Memory Map::			How things are organized.
* Mode swapping::		Getting in and out of real mode.
* MOOSE Interface::		Calling real mode from MOOSE.
* Real mode OSL::		a subset of OSL for use in real mode.

Appendice:
* BIOS services:(BIOS.nfo)	A description of BIOS functions.

File: BIOS-API.nfo, Node: Intro, Up: Top

   The BIOS is a standard preprogrammed hardware IO interface. It's slow,
it's real-mode, it's not reentrant, it provides very few interesting services
at high cost, but, hey, it's there. So why not use it, so we can focus on
higher-level features of MOOSE ? It won't be efficient at all, but it's easily
done, and if we use it through a more intelligent interface, we'll be able to
eliminate it later while still keeping the interface. Lastly, using the BIOS
makes it possible to test MOOSE under OS/2 or Linux (if we manage to get in
protected mode and to use the timer).

Node: Bootstrapping, Up: Top

  An external LOADER (see the BOOTREC.asm and LOADER.asm sources) must put the
API at 0100h:0, and jump into the API Entry Point, whose offset address from
segment 0100h will be at 0100h:0024h (see * API Header::).
  The API will then relocate its permanent part at the top of "conventional"
(under address 640 KB) memory, and install the system at the top of total
memory available in protected mode (actually, only the first 16 MB even if
more is available as some computers won't cache memory above 16 MB). The
system here means the Kernel, the API dynamic linkage information and
initialization code, space for system tables.
  It will then jump into the API initialization routine, which in turn will
eventually jump into the kernel initialization routine.
  What the API initialization routine will do is size the extended memory,
setup the page tables, the interrupt descriptor table, the global and local
descriptor tables.

Node: Memory Map, Up: Top

PHYSICAL MEMORY:
* Conventional memory:
 - space for a regular DOS program.
 - DMA-able buffers for MOOSE.
 - Real-Mode part of the API
* extra RAM between C0000 and EFFFF
* Extended memory
 - Free space for DOS programs
 - (DMA-able ?) Buffers for MOOSE
 - MOOSE Kernel.
 - Above 16MB: Buffers if cached, or else slow buffer/RAM-disk.

LINEAR MEMORY (in bytes)
* 00000000-0FFFFFFF:	(256M)		physical memory mapping
* 10000000-10000FFF:	(4K)		Invalid NULL Kernel page
* 10001000-10FFFFFF:	(16M-4K)	Kernel code, data et al.
* 11000000-3FFFFFFF:	(1G-272M)	Other Kernelish things ?
* 40000000-40000FFF:	(1G)		Invalid NULL User page
* 40001000-7FFFFFFF:	(1G)		User space (fixed objects)
* 80000000-FFFFFFFF:	(2G)		User space (relocatable objects)

SEGMENTS:
* 0000	NULLSEG		00000000-00000000	invalid null segment
* 0008  ?		(reserved)		temporary
* 0010	ALLMEMCS	00000000-FFFFFFFF	all memory (code)
* 0018	ALLMEMDS	00000000-FFFFFFFF	all memory (data)
* 0020	RMPART		?			RM Part of the API (code)
* 0028	RMPART		?			RM Part of the API (data)
* 0030	PMPART		?			PM Part of the API (code)
* 0038	PMPART		?			PM Part of the API (data)
* 0040	KCSEG		40000000-3FFFFFFF	Kernel PL0 Code Segment
* 0048	KDSEG		40000000-3FFFFFFF	Kernel PL0 Data Segment
* 0050	KCSEG		40000000-3FFFFFFF	Kernel PL1 Code Segment
* 0058	KDSEG		40000000-3FFFFFFF	Kernel PL1 Data Segment
* 0060	KCSEG		40000000-3FFFFFFF	Kernel PL2 Code Segment
* 0068	KDSEG		40000000-3FFFFFFF	Kernel PL2 Data Segment
* 0070	KCSEG		40000000-3FFFFFFF	Kernel PL3 Code Segment
* 0078	KDSEG		40000000-3FFFFFFF	Kernel PL3 Data Segment
* 0080	KL0CG		?			Kernel PL0 Call Gate
* 0089	KL1CG		?			Kernel PL1 Call Gate
* 0092	KL2CG		?			Kernel PL2 Call Gate
* 009B	KL3CG		?			Kernel PL3 Call Gate
* 00A0	KTSS		?			Kernel TSS
* 00A8	

* 0061	UCSEG		User Code Segment
* 0069	UCSEG		User Data Segment


Node: Mode swapping, Up: Top
  The API provides means to go from real mode to protected mode and
reciprocally. Thus, the BIOS services or those provided by real-mode
device drivers, TSR's and programs can be called from MOOSE, while
the services those programs call can be intercepted and managed by MOOSE.

  Here are the low-level calls from MOOSE:
- (un)register hardware interrupt handler in exclusive or chained mode.
- (un)register software trap/interrupt in some mode.
- (un)request I/O permission
- (un)secure data zone for DMA.
- (un)request true 100% real-time slice.
- (un)request true real-mode.
- compile, call, or free some OSL code into real-mode in a given VM86 box.
  and from 86-mode:
- yield/terminate execution.
- jump into a given protected-mode address.

  Medium-level calls are constructors for lazily-compiled and automatically
freed real-mode code, or VM86 boxes, save contents of the VM86 box and/or
drivers working in/out/for VM86. And MOOSE object evaluation from real-mode.

  High-level calls are VM-machine control calls (creation, I/O redirection,
program execution, OS emulation directives, etc), and Wrapped Object-Oriented
IO using BIOS or other service.

Node: MOOSE Interface, Up: Top

Node: Real mode OSL, Up: Top

  The real-mode part of the API does not include any OSL support. But
Some mappable/copyable page of memory contains the OSL kernel that can be
used from real-mode applications.
  For anything more complicated than arithmetics & program structure words,
the real-mode code will hook into protected-mode (with all interrupts off ?).
  Hopefully, the real-mode code will eventually hook into protected mode
all the code needed to completely emulate the MS-DOS and its extensions.

