-*- Text -*-
   This is the file .../info/i386impl.nfo, which contains info
about the i386 implementation of the OSL and the MOOSE.

File: i386impl.nfo	Node: Top	Up:(MOOSE.nfo)	Next:Foreword

* Menu:

About the i386 implementation:
* Foreword::			Please read this before.
* Intro::			Why the i386 ?
* Hardware Limitations::	What's wrong with the PC and the i80x86 family.
* OS Limitations::		Why we restricted to essentially flat mode.

The straightforward OSL implementation:
* Overview::			Implementation overview.
* Threads::			How system threads are allocated.
* Register conventions::	Which are saved, which have special meanings.
* Memory allocation::		The memory object.
* Object encoding::		How low-level types are encoded.
* Using objects::		How to call external objects.

Kernel and API:
* Booting the kernel::		How it happens.
* External Kernel entries::	Other entry points for the Kernel.
* API services::		What the API does.
* Virtual machines::		Creating a virtual machine you can control.
* Kernel format::		Binary format for the kernel.
* API format::			Binary format for the API.

Using the Dictionary: the Kernel library.
* Predefined types::		How the basic types are implemented.
* Inter-object communication::	That says it.

Generating code from OSL:
* Direct Threaded::		Generating OSL from OSL.
* Assembling::			The builtin assembler.

Other concerns:
* Mutual protection::		How objects are protected one from the others.

Existing API Implementations:	Implementations of the MOOSE/World Interface.
* Linux API: (LinuxAPI.nfo).	MOOSE working inside Linux.
* BIOS API: (BIOS-API.nfo).	MOOSE using the BIOS for (Disk or other) I/O.
* DOS API: (DOS-API.nfo).	MOOSE using the Dreaded Obfuscated Shitware
				 for I/O.

File: i386impl.nfo, Node: Foreword, Next: Intro, Prev: Top, Up: Top

   We remind you that this way is implementation dependent; you shouldn't
rely on it but for implementation-specific parts of your programs, that should
themselves be well isolated from the rest, and easily replaceable.
   Now, of course, there's only one implementation available by now (and it's
still being developped), so actually, if you really need low-level feature,
here's all you need to hack.
   Moreover, I need to document this implementation for my own use.
I hope these docs will also be useful for others to (re)implement MOOSE on
any architecture, and/or to improve system implementations in general.
   Again, I appreciate any kind of feedback, either positive or negative.
See the main info files for how to send it to me.

Node: Intro, Next: Hardware Limitations, Prev: Foreword, Up: Top

   The i386 architecture --- this term encompasses the i486 improvement and
the Pentium thing --- is cheap and widely available due to various historical
reasons that the author personally disapproves, that is, IBM neglected to
deposit strong copyrights for the stupid IBM PC, and with Intel's silent
approbation, all computer companies built clones and thus created a de facto
standard, and concurrency helped lower prices. Actually, there's a positive
feed-back between low prices, wide-spreadness and concurrency.

   That's why I and many others purchased a PC clone, and why the MOOSE Project
and I decided to develop MOOSE on such platforms, even if its hardware is
horrible to program (not even taking into account that to palliate this feeble
hardware, myriads of different and mutually incompatible extensions were
invented).

File: i386impl.nfo, Prev: Intro, Node: Hardware Limitations,			Next: OS Limitations, Up: Top

   The i386 has financial advantages, but it inherits a horrible stubborn
instruction set with very few registers from its CISC predecessors from the
ancient time. Moreover, the PC compatible board is also horrible to program
due to compatibility with older chips, and incompatibility between newer ones.

File: i386impl.nfo, Prev: Hardware Limitations, Node: OS Limitations,		Next: Overview, Up: Top

   To allow building of the kernel under an existing 32 bit OS (i.e. Linux),
and easier portability to other architecture, an essentially flat model has
been chosen for binaries, with page-level memory (re)mapping. Moreover, using
i386 near pointers allow a quicker code as long as security isn't involved.

   However, if security is a problem, interobject communication will involve
interpretation or long calls and segment munging that'll have been complicated
for not being the usual thing. It may even involve address space swapping and
suches (as under Linux). Programmable use of paging will also allow
inter-object communication and some protection while still in the flat model.
All these can't be used because of OS limitations (Linux allows mmap'ing, but
no easy documented recovery from page faults )-: !
   Well, after all, the standard protection model for unsecure programs
(as the execution of a foreign-compiled Unix or DOS code) will be Unix-like
tasks. After all, communicating with another task is just an easily
implemented specialization of communicating with other machines over a
network. Small tasks (small segments in the usual address space) will be
enough in most cases, while large tasks (with full address space swapping)
may be the default for executing some Unix binary.

File: i386impl.nfo, Node: Overview, Prev: OS Limitations,			Next: Register conventions, Up: Top

   What the system needs implement is a standard way of coding low-level
and mid-level objects. Mid-level to high-level coding is ensured in a more
or less standard way accross machine implementations.
   As for the low-level objects, we need implement a garbage collecting
system, and standard object-invocation procedures/calling conventions,
structure of standard execution threads
   At the mid-level, we need provide standard services.
   At the high-level, we need have provided wrappers for all the useful
lower-level services to access them as standard abstractions.

   Thus, here is the model:
- There is a garbage collection (GC) for addresses between +1GB and +3GB.
 Any possible object reference to these regions must be registered for
 use when a garbage collection may have occured. Any registered object may
 have its value automatically adjusted during a garbage collection.
- Any object has a declared low-level type, that describes its length, its
 mutability, what fields are to be considered as relocatable pointers, or
 how to manage it during garbage collection if it has a non-standard behaviour.
- Allocation is done according to the mid-level type. Each type possesses its
 own allocation pages; well, similar types may share the same pages, if their
 GC behaviour is the same; and a one type can have several allocation heaps,
 if those heaps behave differently or independently with respect to GC.
- Threads may be preemptible or not. Threads using garbage-collected data
 shouldn't be preemptible, or should disable preemption when using relocatable
 data. Real-time threads not using any garbage-collectable data will be run
 anyway preempting less priviledged threads. Among them, one sets a flag
 so that a low-level PAUSE instruction will actually yield execution only if
 the current thread lasted long enough, but will return *very* quickly to the
 current thread otherwise.
 - An interface to 
 - On 
- ...



File: i386impl.nfo, Prev: Overview, Node: Register conventions,			Next:Object encoding, Up: Top

File: i386impl.nfo, Prev: Register conventions, Node: Object encoding,		Next: Using objects, Up: Top

   The standard object encoding will be a four field structure, each field
being a constant pointer or word representing an aspect of the object. These
fields are:
   - a data field, representing the internal state of the object. It will
typically be a number, or a pointer to a more complex structure.
   - a class info field, representing the interface of the object to the world.
It will be a pointer to a ``virtual table'' of the object's methods' addresses
or other class-related info.
   - a dictionary field, representing the context in which the object is
evaluated. It is a pointer to a structure of variable-value associations.
   - an attribute field, representing annotations given to the object by
other objects. It will be again a structure of associations between the
annotating objects and the annotation.

File: i386impl.nfo, Prev: Object encoding, Node: Using objects,			Next: Predefined types, Up: Top

File: i386impl.nfo, Prev: Using objects, Node: Predefined types,		Next: Inter-object communication, Up: Top

File: i386impl.nfo, Prev: Predefined types, Node: Inter-object communication,	Next: Direct Threaded, Up: Top

File: i386impl.nfo, Prev: Inter-object communication, Node: Direct Threaded,	Next: Assembling, Up: Top

File: i386impl.nfo, Prev: Direct Threaded, Node: Assembling, Next: Top, Up: Top

