                       Custom build (CB) of OS2LDR
                               Version 0.4
                       ===========================

DISCLAIMER:

   All direct and indirect guarantees of the manufacturer of operation
   system are void if OS2LDR (CB) is used to load OS2KRNL.
   
   YOU ARE USING IT AT YOUR OWN RISK. 

   You can use this packet only having valid license to run OS2KRNL.

SYSTEM REQUIREMENTS:

  - Intel Pentium based or compatible system (386, 486 & Cyrix CPUs is
    not supported)

  - ACPI.PSD less than 3.07 will not work with OS2LDR (CB)

  - OS2LDR (CB) may not work with JFSBOOT earlier than 1.07

  - OS2KRNL must be Aurora/eCS only (14.xxx, not w4), UNI/SMP debug/retail.
    When changing from SMP to UNI or backwards, do not forget to
    change DOSCALL1.DLL accordingly.


INSTALLATION:

   To install OS2LDR (CB) copy the contents of this package into root
   directory of the boot drive and edit OS2LDR.INI as required.
   If no OS2LDR.INI found, \OS2KRNL will be loaded by default.

   We highly suggest to save a copy of your original OS2LDR.

TROUBLESHOOTING :
   1. Boot process from JFS partition stops immediately after string 
      "Loading ...", no logo was shown:

      a). Update boot sector on your JFS partition to the last available:
          replace jfs.ifs and ?:\OS2\dll\ujfs.dll to the latest version and 
          run
 
             sysinstx Boot_drive_letter:

      OR
      b). if you have COM1 installed on your PC, try to set os2ldr.ini key

            dbport=0x3F8
    
          as described below

   2. Virtual PC installation hang VirtualPC executable on boot:
      
      remove "serial.snp" string from snoop.lst.

SETUP OPTIONS   :

   Some parameters may be passed to OS2LDR (CB) through OS2LDR.INI
   during the initial startup procedure.

   The format of OS2LDR.INI is as follows:
   ---------------------------------------------------------------------
   [config]
   ; Kernel number from kernel list section to be loaded by default
   default=1

   ; Waiting time (in seconds) after which kernel mentioned in "default"
   ; will be loaded
   timeout=4

   ; Debug options (0 is the wise value ;)
   dbflags=0x19

   ; Debug port
   ; com port address
   ; no debug output if statment is omited (but log still accessible 
   ; through copy from oemhlp$ - see below)
   ;dbport=0x3F8

   ; Enable ctrl-c check for kernel debugger (new kernel only, rev. >=2970).
   ; This option ignored if no debug port specified.
   ; Ctrl-c check can dramatically slow your PC ;)
   ;ctrlc=1

   ; You have full COM port link cable (with hardware flow control support)
   ;fullcable=1

   ; Show PC memory table as it reported by BIOS, do nothing if absent
   ; or defined as 0.
   ; Warning: this option will make PAUSE on boot!
   ;showmem=1

   ; Bit mask to disable vesa mode usage for new logo (new kernel only)
   ; Bit 0 - 256c, 1 - 15bit, 2 - 16bit, 3 - 24bit, 4 - 32bit
   ; i.e. 0x1F - all modes enabled
   ;logomask = 0x1F

   ; Turn off LFB usage for new logo (new kernel only)
   ;nolfb = 1
   
   ; Color values for the startup menu
   ; byte 0 - text color
   ; byte 1 - color of selected row
   ; byte 2 - background color
   ; byte 3 - border color
   ; defauls are:
   ;menupalette=0x0F070F01

   ; Show b/w tty style menu with ugly kernel selection by numeric key ;)
   ; It use BIOS text output only, so suitable for some strange reasons.
   ;ttymenu = 1 

   ; Reset video mode to default 80x25, before menu output (fix for some
   ; strange BIOS bugs too)
   ;resetmode=1

   ; OS/4 kernel only (rev>=2075)
   ; Another way of handling memory files. Kernel will preload all
   ; files, located in:
   ; - BASEDEV and PSD statements of config.sys
   ; - os4krnl.ini
   ; - snoop.lst
   ; - and predefined list of files: PREVIOUS.DAT, ISAPNP.SYS, ISAPNP.SNP, 
   ;   RESOURCE.SYS, CLOCK01.SYS, SCREEN01.SYS, KBDBASE.SYS, SNOOP.LST,
   ;   PNP.SYS, ACPI.CFG, IBMKBD.SNP, PCIBUS.SNP, PREVIOUS.ACP, PCIDEV.TBL
   ; Any other file will assume ZERO size while first boot stage!
   ;
   ;preload = 1


   ; Kernel list
   [kernel]
   <os2krnl_file> = <os2krnl_desc>[,<opt> [,<opt>...]]
   .... (other os2krnl definition lines if required)
   ---------------------------------------------------------------------

   where
   <os2krnl_file> - file with OS/2 kernel
   <os2krnl_dsc>  - any text string to describe <os2krnl_file>

   <opt>          - single kernel file options like:

       MEMLIMIT=X - memory limit in Mb for kernel usage
                    where X is more than 16 and less than total memory

       NODBCS     - disable DBCS file loading (os2dbcs, os2dbcs.fnt)

       ALTF1      - same as pressing Alt-F1 when OS/2 brick is shown
       ALTF2      - same as pressing Alt-F2 when OS/2 brick is shown
       ALTF3      - same as pressing Alt-F3 when OS/2 brick is shown
       ALTF4      - same as pressing Alt-F4 when OS/2 brick is shown
       ALTF5      - same as pressing Alt-F5 when OS/2 brick is shown
       ALTE       - same as pressing Alt-E when OS/2 brick is shown
                    (run kernel config.sys editor - OS/4 kernel only,
                    this option turn on NODBCS)

       CTRLC      - the same as above, but for single kernel only
   
       SHAREIRQ=x - set the bit mask of shared IRQs.
                    For example 0x8000 means that IRQ15 is shared
                    and all other interrupts are exclusive.
                    IRQ2 must be always set as exclusive.
                    If this option is absent, the system will use the
                    default bit mask 0xFFF8.
                    This option may be useful in non-ACPI systems with
                    troublesome configurations (it is suggested to avoid
                    this option if you do not understand what it does).

       CHSONLY    - int13 extensions will not be used during startup 
                    procedure

       LOGSIZE=XX - set log size for debug to XX kilobytes.
                    The value will rounded down to nearest 64k border, but not
                    lower 64k.
                    This key can be added to config session (for all kernels)
                    Boot log avalable by copying it to file:
                       "copy ___hlp$ boot.log"  on PC with ACPI.PSD used
                       "copy oemhlp$ boot.log"  on PC without ACPI.PSD

       NOREV      - do not show kernel revision (new kernel only)

       NOLOGO     - do not show logo (new kernel only). This key is accepted
                    in common ([config]) section too. You can also press AltF7
                    in loader menu to turn off logo (both IBM & OS/4 kernels).

       CFGEXT=EXT - use CONFIG.EXT file for boot, instead of CONFIG.SYS
                    File must be placed in root directory.
                    EXT - custom file extension, up to 3 chars.
                    This option works with all old kernels as well.

       SYM=FILENAME - use FILENAME as SYM file for DEBUG OS/4 (OS/2) kernel.
                    Filename is up to 11 chars length (7.3, limited by patching
                    original IBM kernels)

       PRELOAD    - preload files (see above, new kernel only). This key is
                    accepted in common ([config]) section too. You can also
                    press AltF8 in loader menu to turn on this option on boot.

       RESTART    - this option turns off ALL the above and assumes specified
                    file name as another (old) OS2LDR.
                    On this entry selection loader read this file and
                    run it as OS2LDR.

       ";"        - in first row only considered as beginning of a comment line


   Example of kernel list section:

   ---------------------------------------------------------------------
   [kernel]
   ; load os2krnl.086 without DBCS, with 55Mb of memory and Alt-F1
   ; pressed
   os2krnl.086=Revision 14.086_UNI,NODBCS,MEMLIMIT=55,ALTF1
   ; load os2krnl.104
   os2krnl.104=Revision 14.104a_SMP
   ; load old os2ldr (named os2ldr.old on disk) and launch it
   os2ldr.old=Old boot, Restart
   ; load os2krnl.smp and boot it with CONFIG.NEW instead of
   ; CONFIG.SYS and without logo
   os2krnl.smp=My favorite 15.1_SMP,CFGEXT=NEW,NOLOGO
   ---------------------------------------------------------------------

   Maximum size for OS2LDR.INI - 8kb, larger file will be ignored on boot.

LOADER MENU OPTIONS:
   The following keys supported in OS2LDR (CB) loader menu:
   - Alt-F1 .. Alt-F5 - standard keys, will be sent to boot kernel
   - Alt-F7 - turn boot logo off (IBM kernels too)
   - Alt-F8 - turn on preload files (OS/4 kernel)
   - Alt-E  - call boot config.sys editor. 
              (OS/4 kernel, edited config used for current boot only and
              will be not saved anywere).

CONTACTS:

   If any bug appears please make sure before reporting that it does not appear
   with the original OS2LDR. Bug reports should be sent to:

     http://tracker.os4.su
   or 
     os2ldr@gmail.com.

   
========================================================================

Appendix A. TECHNICAL NOTE FOR DRIVER DEVELOPERS:

You can write to the OS2LDR log from your own driver by using the following
method (16 bit C code example):

  void (far *PrintLog)(char far*) = 0;

  // make pointer to DOSHLP code (this is constant value for all OS/2 versions)
  ULONG FAR *OS4LDR = MAKEP (0x100,0);

  // check OS/4 loader signature at DOSHLP:0 seg
  if (*OS4LDR==0x342F534F) {
     OS4LDR++;
     // check OS/4 loader info struct size
     if ((*OS4LDR & 0xFFFF) >= 0x30) {
        USHORT FAR *ptr = (USHORT FAR *) OS4LDR;
        SELECTOROF (PrintLog) = 0x100;
        OFFSETOF (PrintLog) = ptr[0x17];
     }
  }
  if (PrintLog) (*PrintLog)("Hello, log!\n");

PrintLog support for a tiny printf format subset:
   %x       - print argument as a hex word (16 bit)
   %d       - print argument as decimal word (16 bit)
   %c       - print argument as ascii character
   %b       - print argument as hex byte

To call PrintLog with armuments define it as:

  void __cdecl (far *PrintLog)(char far *fmt,...) = 0;

========================================================================

  OS/2 is a registered trademark of IBM Corporation.
   
  Intel Pentium is a registered trademark of Intel Corporation.



  2008-2010, Team OS/4.
