                       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.

   3. There are many options to reduce possible problems on boot:

      * remove dbport key and especially dbport=0 key ;)

      * remove boot logo (OS/4 kernel) - this can help with some nvidia/intel
        motherboards (Alt-F7 in menu make this once, for current boot only).

      * slightly reduce available memory by using MEMLIMIT key (some BIOSes
        can incorrectly report system areas on the top of memory as free)

      * it is a good idea to use multiple configs by CFGEXT key (one stable 
        and one for configuration changes)


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. This is optional for kernels
   ; beginning from revision 2970. Older kernels always have this check enabled.
   ; This option ignored if no debug port specified.
   ; Ctrl-C check allows KDB popup when Ctrl-C is passed via serial link but
   ; adds two problems:
   ; - frequent serial port reads cause overall performance degradation
   ; - the serial port can't be used for something else except KDB because these
   ;   reads destroy data which are received by the port
   ;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

   ; Hide from OS/2 one of memory blocks from list above.
   ; Block specified by start address (>1Mb, block at 1Mb required for OS/2
   ; boot). 
   ; You can add up to five such keys into [config] section.
   ; note: OS2LDR ignore too small blocks (<64k) by itself.
   ;removemem=0x20000000

   ; 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)
   ; Turn on 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
   ;
   ;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 "ctrlc=1" in global section but only for this
                    loading configuration

       DBPORT=x   - the same as "dbport" in global section but only for this
                    loading configuration. This option overload global setting.
                    You can specify -1 here to turn port off for this line.

       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

       NOLOGO     - do not show logo. This key 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.
                    The used maximum length depends on loader of this SYM.
                    In LOADSYM mode the limit is 16 chars. Otherwise it is 11
                    chars (7.3, limited by patching original IBM kernels)

       LOADSYM    - the kernel SYM is loaded by OS2LDR directly so kernel can
                    take it from memory without miniFSD using. The option is
                    required to load a SYM into OS/4 kernel starting from r4058.
                    Older kernels are not broke with it. They just ignore the
                    passed SYM file content. The name of file to load is taken
                    from SYM option or calculated as selected kernel file name
                    with ".SYM" suffix appended.

       MFSDSYM=FILENAME - use FILENAME as SYM file for miniFSD. Without this
                    option it will be no attempt to load the mFSD SYM because
                    microFSD doesn't report how even mFSD itself is named.
                    Maximum length of the name is 16 chars. Subsequent chars are
                    ignored.

       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 column 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
   %s       - print argument as string (far 16 bit)

To call PrintLog with armuments define it as:

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

ASM 16 code example:
                   Public   DebPrintf                                ;
DebPrintf          Proc     Far                                      ;
                   push     di                                       ; use di
                   SetSeg   _DATA16, <ds>, di                        ; set own data segment
                   test     Word Ptr DHPrintf+2, 0ffffh              ; is exist?
                   jnz      short @@DBPrtRet                         ; Yes, go to print
                   call     DebInit                                  ; No, try init 
@@DBPrtRet:                                                          ;
                   pop      di                                       ; restore
                   jmp      Dword Ptr DHPrintf                       ; goto Ldr Printf
DebPrintf          EndP                                              ;
DebInit            Proc   Near                                       ;
                   push   es                                         ;
                   SetSeg _DATA16, <ds>, di                          ;
                   mov    di, 100h                                   ; set LDR seg
                   mov    es, di                                     ;
                   cmp    Dword Ptr es:0,  342F534Fh                 ; check OS/4
                   jne    Short @@DBInitRet                          ;
                   cmp    Word Ptr es:4, 30h                         ; check version
                   jl     short @@DBInitRet                          ;
                   mov    Word Ptr DHPrintf+2, 100h                  ; save seg
                   mov    di, Word Ptr es:4+17h*2                    ; save offs
                   mov    Word Ptr DHPrintf, di                      ;            
@@DBInitRet:                                                         ;
                   pop    es                                         ;
                   ret                                               ;
DebInit            EndP                                              ;

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

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



  2008-2010, Team OS/4.
