-*- Text -*-
   This is the file .../MOOSE/info/GOOSE.nfo, which contains info
about GOOSE: Generic OS-independent Object Saving Encryption
GOOFY: Generic OS-independent O File Y
SOFT: Saved Objects File Technique
WILD: Way of Intelligently Loading Data
AIDS: Architecture-Independent Data System
EEEE: EEEE Emits E's Everywhere
PIGMALION: Processor-Independent Generic Medium A L Information Over Network


* {/G}: Generic
* {/P}: Practical
* {/I}: Intelligent
* {/U}: Useful
* {P/O(S)/S/A}(I): Processor/Operating-System/System/Architecture Independent
* {O/D/I}: Object, Data, Information
* {C/I/S/L/F} :Communication/Interchange/Saving/Loading
* {/F/M/E/C}: File, Medium, Encryption, Code
* {/T/W/S/F/C/E}: Technique, Way, System, Format, Convention, Encoding




File: GOOSE.nfo		Node: Top	Up:(i386impl.nfo)

* Menu:

* Intro::			What's GOOSE ?
* Overview::			The Generic OO Object File Format we use.

* Data oriented look		How object files are encoded.
--------------------
* Signature::			Some stuff associated to any MOOSE object,
				including file size, word size and byte order.
* Segmenting::			A GOOSE file, like any MOOSE object, may (and
				actually will) be segmented into subfiles.
* Standard Segments::		Segments recognized by the system.


* External Code oriented look	How an external program uses the object file.
-----------------------------
* Bootstrapping sequence::	How to boot the code.
* Kernel/API interface::	How the Kernel and the API communicate.
* External interface::		How the External World and the API communicate.

* Internal Code oriented look	How code in the object must be written.
-----------------------------
* Importing external data::	
* Exporting internal data::	

* Other ways to look at GOOSE
-----------------------------
* Processor dependencies::	Word size, byte order, alignments, etc.

File: GOOSE.nfo, Node: Overview, Next: , Prev: , Up: Top

   GOOSE stands for Generic OS-independent Object Saving Encryption.
That's the Coding Standard we choose to store/load/send/receive MOOSE objects,
on mass storage media or over a network of computer.

   GOOSE files are a particular kind of low-level MOOSE objects, designed to
represent objects in a standalone way (i.e. without machine-state dependencies,
not linked in-memory with other objects). There are several (as few as
possible) actual GOOSE file formats, the translation from one to the other
being straightforward; each format tries to ease the dataflow between the
storage or broadcast media and the particular computer that will use it.


Node: Signature

   Any MOOSE low-level object has at least two attributes: its low-level class,
and its size into memory. Those two attributes must always be available when
such low-level object is considered.

   Most machines have are binary machines whose word size (in bit) is a power
of two; but some do not. Most machines also can address 8-bit bytes. GOOSE
uses such systems as a base; but describes changes for other systems.
   This file format is generic enough to work on any kind
of machine; however, when machines with different word size or byte order must
communicate, a conversion must occur somewhere, and we demand that machines
with the unusual word size do provide the conversion tools (the tools may run
on the unusual machine or on the usual one).

   Thus, when

Node: Segments

  A segment is the embedding of a subfile inside the file itself.
Segments:
each segment is preceded by its length then its type.
The length does not include this header.
The beginning of the segment is just after the header.
Segments are one after the other.

* Headers::			Signature and the like.
* Exports segment::		Where the OSL/World Interface begins.
* Strings segment::		Where ASCII strings are stored.
* Binary segment(s)::		Where the remaining is.

Node: Header Segment

   A signature allows identification of a GOOSE file as such. It permits the
system not to use the first come trash file as an executable file. It also
contains information about particular characteristics of the file, such as
byte order used, languages or encodings (including version) recognized or
needed.

   A GOOSE file thus begins with a 32-bit "Magic number" #2099BDE7h (see file
MOOSE/boot/M_Magic). The byte order of the magic number is the default byte
order used in the rest of the file. Other magic numbers will be choosen for
atchitectures with different word size.

   The first magic number is followed by the 32-bit total size of the file, NOT
including the magic number and the size itself.

Node: Processor dependencies

   Each processor has its own size for coding numbers, characters,
memory addresses.

   In this text, a ``byte'' will mean some standard 8 bit code, as most
networks or magnetic media use. Whether a particular machine actually
use an 8 bit byte or a larger representation for it is irrelevant here.
A ``char'' will be such usual machine representation for a byte. It may
be much larger, but when used to encode a byte, its value may not be
outside the range 0-255. An ``word'' is a double byte value (the order of
the msb and lsb being the network order). A ``short int'' is a machine memory
cell at least capable of coding a word. A ``double word'' is a four byte value,
and a ``long int'' is a machine representation capable of coding such a thing.
An ``int'' is one of short int or long int, able to represent the address of
a memory cell.

   It is assumed that byte <-> char,int,etc conversion is done transparently
when the network is used, so that any machine ultimately receives or sends its
data in the format best suited for any particular object.


Strings:
- there are several formats (useful for compression schemes), both in-disk and
 in-memory. Compression can be require or not growing global
- the string file may be itself divided in string subfile. What
- 

Strings/text Formats:

* (Uncompressed) raw list of "C" string:
- "C" style zero-terminated strings one after the other.
- a pointer is the offset of the beginning of the string from the beginning of
 the file.

* Ziv-Lempel format with info for local decompression.
- strings are first reencoded with a process that produces fixed length tokens
 (less than 500 combinations ?).
- the produced text is compressed with a varying-length Ziv-Lempel compression
 scheme (see .GIF file format).
- A table is given at the beginning of the file that tells the length of the
 different areas where number of bits is given, so that pointing to a token is
 accurate.
- pointers point to a token in the compressed code + byte for place of
 character in tokenized string.

* Dictionary based compression.
- first comes a list of dictionaries (each a list of words), the encoding of
 each dictionary may depend.
- dictionary (with words frequently used), then text. huffman compression for
 most frequently used words/tokens. Separate compression of words and spacing,
 allowing ZRL for spacing between words. The dictionary can have itself several
 language-dependent
- standard predefined dictionary and/or huffman tables exist for common
 languages, associated with opened modules...








GOOSE identifiers:
a goose file has a GOOSE version number. All numbers in the file are relative
to the given encoding. GOOSE numbers are attributed in an arbitrary but
standard order by a global commitee. Users are invited to use random numbers
between -2^30 and -1. Look at how the magic numbers for GOOSE where found
(file boot/M_Magic.h).

Low-level security:
a GOOSE file can have many states:
* blindly trusted: no checks are done at all. This is the case when the file
* trusted: format consistency checks are done, but whatever is said is believed
* partly trusted: the file itself is trusted, but not the execution.
* 
* untrusted: 
* completely untrusted: all the redundant information is checked.

By default, the booting object is blindly trusted, but it can put the whole
remaining system in trusted mode only, or even in completely untrusted mode.
It is strongly recommended that open systems (not working standalone in a
hostile environment), there exist somewhere a "door" that allows new blindly
trusted code to patch the system.