****************************************************************************
*                                                                          *
*   PASS32 32 Bit Assembler               written by Dieter Pawelczak      *
*                                                                          *
*                      Pass32 supported File Formats                       *
*                                                                          *
*   (c) 1996,1997 by Dieter Pawelczak, Fasanenweg 41, 85540 Haar, Germany  *
*                                                                          *
****************************************************************************

This file contains a description of the file formats supported by the Pass32
assembler:

1. DOS TINY BINARY FORMAT (.COM)
2. PRO32 DOSX 32 BIT BINARY FORMAT (.EXE)
3. 32 BIT FLAT 3OS BINARY FORMAT (.3OS) (V2.4 only)
4. FLAT MEMORY OVL BINARY FORMAT (.OVL)
5. FLAT MEMORY DLL BINARY FORMAT (.DLL)
6. FLAT MEMORY PRO32 PLUG-IN BINARY FORMAT (.DLL)  (Pro32 Gold only)
7. FLAT MEMORY BINARY (.BIN)

1. DOS TINY BINARY FORMAT (.COM) ============================================

The DOS .COM Format is a binary format with max. 65280 Bytes size. The
binary file actually presents the program code which is load at the offset
0100h:

     File Contents:                       Load to Memory by DOS:

  ͻ    ͻ
   Program Binary                      PSP 0000h - 00ffh              
                                                                      
   Main Program 0100h                 ͹
                                       Main Program    0100h          
   .CODE                               .CODE                          
                                                                      
  ͹    ͹
   Main Program predefined Data        Main Program predefined Data   
   .DATA                               .DATA                          
  ͼ    ͹
                                         Main Program undefined Data    
                                         .DATA?                         
                                                                        
                                        ͹
                                         HEAP and Stack         -0ffffh 
                                        ͼ

2. PRO32 DOSX 32 BIT BINARY FORMAT (.EXE) ===================================

The Pro32 binary format is actually equal with the DOS .COM format, but
there's a) no limit in size (4GByte) and b) the segment attribute must be
32 bit.

The Pro32 stub file (PRO32.EXE) is linked at the beginning of the file.
This "specialized" Pro32 Version will contain additional data specified for
the individual program. These additional data fields are called the
Extender Variables (see proset.doc, pass32.doc, pass32.txt).

So next to the flat binary file two data blocks are actually part of the
Pro32 binary format: The Pro32-Header block and the Pro32-Plug-In block.
The Pro32-Plug-In block is used only in the Pro32 GOLD series.

    Pro32-Header Block:                   Pro32-Plug-In Block:

  ͻ    ͻ
   00-03:  "MEM:" - Identificator      00-03: "DLL:" - Identificator  
  ͹    ͹
   04-07: DD MinMemory                 04-0b: 1. DLL NAME             
  ͹    ͹
   08-09: DW Header Size               0c-13: 2. DLL NAME             
  ͹    ͹
   0a   : DB Flag NoBreak              14-1b: 3. DLL NAME             
  ͹    ͹
   0b   : DB Flag NoMesg               1c-23: 4. DLL NAME             
  ͹    ͹
   0c   : DB Flag WriteCore            1c-23: 5. DLL NAME             
  ͹    ͼ
   0d-10: DD Core Size            
  ͹
   11-14: DD Load Offset          
  ͹
   15-18: DD Entry Point          
  ͹
   19-1a: DW Version              
  ͹
   1b   : DB Wait Flag            
  ͹
   1c-1f: DD MaxMemory            
  ͹
   20-23: DD Stack Size           
  ͼ

For the Plug-In names only 8 bytes are reserved. The name can consist
of 7 characters and a NUL-character as last character. Basically the list
of plug-ins has no specific size. The first plug-in name that consists
only of a NUL-character defines the end of the list. Nevertheless, Pro32 GOLD
reserves only 5 plug-ins.



3. 32 BIT FLAT 3OS BINARY FORMAT (.3OS) ===(V2.4 only)=======================

The 3OS format is an open binary format which is compatible with the Pro32
binary format. It is used to load 32 bit binaries which are not bound to a
dos extender.
As an open format, it can consist of several different headers. Each header
has a 4 byte header identifier. A loader program is responsible to analyze
the headers and load the binary into memory.

The 3OS format supported by Pass32 consists of the Pro32-Header and the
Pro32-Plug-In block. For compatibility with the DLL model, the MinMemory
item is at offset 0ah. Pass32 supports only 5 plug-ins in the Plug-In
Block.

Note: any loader which can handle Pass32 programs (Proset, ProDB32, etc.)
can handle the 3OS format as well.

The Pass32 3OS output format:

  ͻ
   00-05: reserved == 00h         
  ͹
   06-09: "MEM:" - Identifier     
  ͹
   0a-0d: DD MinMemory            
  ͹
   0e-29: ... Rest of Pro32-Header
  ͹
   2a-4f: reserved == 00h         
  ͹
   40-63: Plug-In-Header          
  ͹
   64-cf: reserved == 00h         
  ͹
   d0-ff: Copyright Comment       
  ͼ

  Header Size, Load Offset, EntryPoint = 00000100h

If you compare the Pass32 3OS Format with the Pro32 PLUG-IN format, you'll
notice, that the essential data is equal in both formats. Therefore, you
can design Pro32 Plug-Ins as DLL or as 3OS binaries. Note, this relation
is valid only for the Pass32 3OS output! Basically the 3OS format is an
open format and not compatible with the Pro32 Plug-In format!!!



4. FLAT MEMORY OVL BINARY FORMAT (.OVL) =====================================

The OVL format is a very simple format. It consists of an interface part
and the binary source. The interface part is a multiple of 256 bytes in
size and contains the offset addresses of the public OVL procedures.

Pass32 supports only a 256 byte long interface part. Here is the complete
definition of the OVL format:

  ͻ
   00-03: Load Offset - start address of the OVL        
  ͹
   04-1F: reserved for future applications              
  ͹
   20-23: offset of the first procedure                 
  ͹
   24-25: selector of the first procedure               
  ͹
   26-FE: pointers of the second to 37th procedure.     
  ͹
   FF   : interface chain marker 00=END                 
  ͹
   00000100h - : code/data segment of the overlay       
  ͼ

The initial selector value is 0000h. The offset address is absolute.

If the interface chain marker is unequal zero, another interface part
follows. As the first 20h bytes needn't be reserved in the following
interface parts, the following interface parts contain only the offset
addresses of the public procedures:

  ͻ
   00-03: offset of the next (38th) procedure             
  ͹
   04-05: selector for future applications                
  ͹
   06-FC: offsets and selectors of the next 41 procedures 
  ͹
   FD-FE: reserved = 0                                    
  ͹
   FF   : interface chain marker 00=END                   
  ͼ

The binary is already compiled to the fixed start address given in offset
00-03 of the interface part.
The OVL loader code is part of OVLSYS.INC and will be automatically linked
with the source code if an overlay module is included.



4. FLAT MEMORY DLL BINARY FORMAT (.DLL) =====================================

The Pass32 DLL Model is not compatible with other dynamic link libraries
formats. The only thing in common is the idea of loading additional functions
dynamically during the program execution.
A good example of the DLL usage is the graphic driver interface: a graphic
library with a common interface to a series of different graphic DLLs.
Like the OVL format, the idea was to create a very simple DLL format, so
that very easy DLL loaders can load and install the program code and the
interface.

The Pass32 DLL format is similar to the OVL format. Again, Pass32 supports
only a 256 byte DLL header.

  ͻ
   00-09: reserved - unused                             
  ͹
   0a-0d: amount of memory needed for the DLL           
  ͹
   0c-1f: reserved - unused                             
  ͹
   20-23: offset of the first procedure                 
  ͹
   24-25: selector of the first procedure               
  ͹
   26-FE: pointers of the second to 37th procedure.     
  ͹
   FF   : interface chain marker 00=END                 
  ͹
   00000100h - : code/data segment of the DLL           
  ͼ

The initial selector value is 0000h. The offset address is absolute.
Additional DLL headers are equal with additional OVL headers:


  ͻ
   00-03: offset of the next (38th) procedure             
  ͹
   04-05: selector for future applications                
  ͹
   06-FC: offsets and selectors of the next 41 procedures 
  ͹
   FD-FE: reserved = 0                                    
  ͹
   FF   : interface chain marker 00=END                   
  ͼ

The Pass32 DLL loader DLLSYS.INC sets the initial PSP values for the
DLL. When the DLL is load, the DLL can access these data fields via the
CS descriptor:

  ͻ
   00-01:  Value of the DLL Data Descriptor (DS)          
  ͹
   02-03:  Video Selector                                 
  ͹
   04-05:  Zero Selector                                  
  ͹
   06-07:  Real Mode File Buffer Selector                 
  ͹
   08-09:  Real Mode File Buffer Segment Value            
  ͹
   0a-0d:  DLL Memory Size                                
  ͹
   0e-11:  DLL Memory Handle  (DPMI: SI:DI)               
  ͹
   12-13:  Value of the DLL Code Descriptor (CS)          
  ͹
   14-17:  DLL Linear Memory Address                      
  ͹
   18-19:  Value of the Main Program Data Descriptor      
  ͹
   1A-1F:  reserved                                       
  ͼ



6. FLAT MEMORY PRO32 PLUG-IN BINARY FORMAT (.DLL)

A Pro32 plug-in is compatible with the DLL and the 3OS format.
The only important parameter is the memory usage at offset 0ah.
Pro32 starts a plug-in always at offset 00000100h.

  ͻ
   00-09: reserved - unused                             
  ͹
   0a-0d: amount of memory needed for the DLL           
  ͹
   0c-1f: reserved - unused                             
  ͹
   20-23: offset of the first procedure (ignored)       
  ͹
   24-25: selector of the first procedure (ignored)     
  ͹
   26-FF: unused                                        
  ͹
   00000100h - : code/data segment of the DLL           
  ͼ


PASS32 (c) 1996,1997 by Dieter Pawelczak,
PASS32 DLL Format (c) 1996-1998 by Dieter Pawelczak,
PASS32 OVL Format (c) 1996-1998 by Dieter Pawelczak,
3OS Format (c) 1998 by Dieter Pawelczak,

Pass32 Version 2.4 (c) 1998 by D. Pawelczak

email: dieterp@bigfoot.de
www  : Pass32 Home:
       http://www.geocities.com/SiliconValley/Bay/3437/index.html
       Personal Home:
       http://www.geocities.com/SiliconValley/Bay/9159/
       http://www.eikon.e-technik.tu-muenchen.de/~et_514/
