Phoenix OS/4

Phoenix OS/4 is a project intended to recreate the original kernel for the IBM Operating System/2 using such techniques, as reverse-engineering and disassembling. The main goal of the project is to make the system able to work on the PCs, that it is unable to work on with the original kernel.

Installation instructions
From now, we assume that you downloaded the latest OS/4 kernel distribution zip file, and it is named like this:

os2krnlSVNxxxx_unoff.zip, where xxxx is the SVN revision of the downloaded release. To clarify the following installation instruction, it is assumed, that the downloaded distribution file's name is os4krnl_current.zip. Please, rename the downloaded file to os4krnl_current.zip using your favorite filemanager or the CMD.EXE's ren command like this: ren os2krnlSVNxxxx_unoff.zip os4krnl_current.zip. Also, you will need the unzip utility, which you can find on hobbes. A more up to date (capable of handling files larger than 2 GB) version can be found at Paul Smedley's OS/2 ports site

Okay, so everything is prepared -- let's begin!

The OS/4 distribution package includes a powerful kernel loader, which features loading OS/4 and OS/2 kernels, kernel selection menu, custom CONFIG.SYS files for each kernel, CONFIG.SYS editor which may be invoked right before the kernel loads (available on OS/4 kernels only; although the modified version of the config is not put back on the disk, the feature is fairly useful in crash recovering), chainloading another kernel bootloaders and preloading files in the memory (better boot time).

So, the first thing to do, is to install the OS/4 kernel bootloader, because the original one is unable to load the OS/4 kernel. If you use a recent version of ACPI, original kernel, or both (you have eCS), then it is highly recommended to keep the original bootloader:
 * unset the hidden attribute of the original kernel bootloader: attrib -H \OS2LDR
 * rename OS2LDR</tt> to OS2LDR.IBM</tt>: ren \OS2LDR OS2LDR.IBM</tt>
 * extract OS2LDR from the OS/4 package to the root of the boot drive: unzip os4krnl_current.zip OS2LDR -d \</tt>

Then extract the Phoenix OS/4 kernel to the root of the boot drive (the file is named OS4KRNL for the debug version and OS4KRNLR for the retail version):
 * we will use the retail version, so do unzip os4krnl_current.zip OS4KRNLR -d \</tt>.

OS/4 ships also with an updated DOSCALL1.DLL</tt> library, which works fine with both kernels (highly recommended):
 * download the lxlite package from hobbes (eCS already has this tool, although there is some argument about the way that it works. Any version should do what is necessary).
 * extract the unLock.exe utility to your PATH, for example, to the \OS2 directory: unzip -j lxlt133.zip lxLite\unLock.exe -d \OS2</tt>
 * now unlock your current DOSCALL1.DLL file: unlock \OS2\DLL\DOSCALL1.DLL</tt>
 * rename it for a backup: ren \OS2\DLL\DOSCALL1.DLL DOSCALL1.IBM</tt>
 * and then extract the Phoenix version: unzip os4krnl_current DOSCALL1.DLL -d \OS2\DLL</tt>

Then you need to configure the OS/4 kernel bootloader to be able to load the original, and the Phoenix kernel. The configuration file's name is OS2LDR.INI. An example configuration file is present in the distribution package, and contains a comment for each line. Note that this is a TEXT file, not a binary INI file.

Create an empty OS2LDR.INI file in the root of the bootdrive and then put this in it using a text editor (or whatever you want): [config] default=1 timeout=15 [kernel] OS2LDR.IBM = IBM orig. kernel ,RESTART OS4KRNLR  = Phoenix kernel   ,PRELOAD The default</tt> statement in the config</tt> section sets the default selection in the kernel selection menu, and the timeout</tt> statement sets the time in seconds before the default kernel will be loaded.

In the kernel section, the statements must comply with the following syntax:

= <kernel selection menu option text>[,option[=value][,option[=value][,option[=value][...]]]] The possible options are:

Although the original kernel may be loaded by the OS/4 kernel bootloader directly, the most stable configuration is to use original bootloader to load the original kernel.

Notice, that the original bootloader (OS2LDR.IBM) is able to load only the kernel file, named OS2KRNL, and you have to keep the original kernel with that name to have the ability to load it with the original bootloader.

Also notice, that although you have the ability to chainload kernel bootloaders with custom name using the Phoenix bootloader, the first loaded kernel bootloader is always named OS2LDR.

There are also some configuration statements you can use in the config</tt> section in the Phoenix bootloader configuration file, but those are usually only useful for debugging and troubleshooting purposes. See the example OS2LDR.INI file in the OS/4 kernel distribution package.

This is a basic installation process, but remember, that there is also a new CLOCK03B.SYS</tt>, which supersedes original TIMER0.SYS</tt> and <tt>CLOCK01.SYS</tt> drivers. It is recommend to install this driver: You don't need to modify <tt>CONFIG.SYS</tt>
 * <tt>unzip os4krnl_current.zip CLOCK03B.SYS -d \OS2\BOOT</tt>

Attention! Since SVN revision 4166, it is mandatory to install the new <tt>SCREEN03.SYS</tt>, otherwise kernel won't boot: You don't need to modify <tt>CONFIG.SYS</tt>, too.
 * <tt>unzip os4krnl_current.zip SCREEN03.SYS -d \OS2\BOOT</tt>

Okay, everything is set up. Now reboot your system!

You should notice the kernel selection menu with two options, where you can select to load either the original IBM kernel, or the Phoenix one. Although you may fail to boot up with the Phoenix kernel due to a bug in it, there is no doubt you will be able to fall back to the original kernel and boot your system with it (if you were able to do this before :) ).

Known problems and not-a-problems

 * Tracing (STRACE and TRACE) feature is discontinued. Phoenix team is not going to make it work again.
 * <tt>VIRTUALADDRESSLIMIT</tt> adjusting feature is accidentally broken. Will be fixed ASAP in future releases.
 * Booting from FAT16 partition is broken in the OS/4 Loader. It is a bug, and will be fixed ASAP in future releases. If you need to boot from FAT16, use QSINIT.
 * The current way to display bootlogo is very outdated, poorly written, and the maximum color depth is only 8-bit (256 colors), so Phoenix decided to rewrite this part. The new way to show bootlogo is not ready yet, and the old one is broken. Await the new bootlogo in future releases.
 * Current alternative loaders (both OS/4 Loader and QSINIT) are unable to load 105_SMP with recent ACPI (something IBMKBD.SYS related), and there is no information if that will be ever fixed. As a workaround, with the original kernel you should use the original bootloader, which you can boot from OS/4 or QSINIT loaders using the RESTART feature.

Getting the log
The traditional way of getting the kernel log (and the only way now to remotely debug it), is to connect a terminal (a PC) to the COM port. You will need a terminal program on the other side (I suggest using DTerm) set up to work on the speed of <tt>115200</tt> baud, bits <tt>8n1</tt> and <tt>no flow control</tt>.

If your debug PC (the one which kernel's log you want to get) doesn't have a COM port, then there's a note at the end of this section for you. If your debug PC has one COM port, it is likely to be the COM port number one and have the <tt>0x3F8</tt> address, so put this setting in the <tt>config</tt> section of <tt>\OS2LDR.INI</tt>:

dbport=0x3f8 If your PC has more than one COM port, ensure you're using the first one for debugging, or, if not, fix this, or set the proper address for the COM port you use, like <tt>0xEC00</tt> for second COM port (you can see the addresses in your BIOS, or you can use the OS/2 Hardware Manager for that).

To turn on debugging over COM port, set the following setting in the <tt>config</tt> section of <tt>\OS2LDR.INI</tt>:

dbflags=0x11

Important thing: you should use the debug kernel to get the log, so extract the debug kernel file to the root of the boot drive:

unzip os2krnl_current.zip OS2KRNL -d \ and modify the <tt>kernel</tt> section of <tt>\OS2LDR.INI</tt> to be able to load it.

Anyway you would like to try the debug one, because the retail kernel may have some bugs already fixed in the debug one, so if you encounter any problems, please try the debug one.

This is already enough to get the kernel log, so you may just fire up the terminal program and load the debug kernel when you're all set up. Please note, that the log is big enough to not fit in the console window, so you would like to turn on the logging feature in your terminal program (Control-L in DTerm).

Additionally, if you have a full COM cable, you may try putting <tt>fullcable=1</tt> in the <tt>config</tt> section of <tt>\OS2LDR.INI</tt>, and turning on the hardware flow control in the terminal program (Control-F in DTerm) -- it helps if you notice missing characters in the log.

Now, if your system traps, the trapscreen will be sent over the COM port, and the Kernel Debugger command promt will appear:

## You can try entering the question mark in terminal -- the Kernel Debugger (aka KDB) will show you the help screen. The most useful command for a user is <tt>.reboot</tt> ;)

Also, if you reported a bug, you may be asked to trap the system and enter some commands for the KDB into the terminal, and show your output to the kernel developer. For some KDB commands to work properly, you need the symbol files (at least of the kernel) to be loaded. The symbol files must be in the root of the boot drive, or in the same directory of the program the symbol file is generated for. So, for OS4KRNL, put OS4KRNL.SYM in the root of the boot drive:

unzip os4krnl_current OS4KRNL.SYM -d \ If the name of the debug kernel you load differs from OS4KRNL, rename the symbol file to correspond to its name:

ren OS4KRNL.SYM KERNNAME.SYM where KERNNAME is your current custom name for the kernel.

Now, to make the kernel to try to load the symbol files, add the <tt>LOADSYM</tt> option to the kernel setup string in the <tt>kernel</tt> section of <tt>\OS2LDR.INI</tt>.

So, if you don't have at least one COM port, there are still some possibilities: ...

TODO: Write this section. Dbanet (talk) 19:44, 3 April 2014 (CEST)

Participating in testing
Testers are highly appreciated. By testing our kernel, you are helping the whole OS/2 community to make OS/2 runnable on every PC in the world. To begin testing, just take the latest debug kernel and try to run it on every PC you can see.

If you didn't run into problems, -- hooray! -- but if you did, that's why there is the section...

Getting the binary distributions
Currently, the download section on the RU/2's Core/2 is outdated (will be fixed ASAP).

The latest kernel distribution should reside on the gus.biysk.ru server in the /os4 directory.

You should find there a ZIP file in the root, starting with os2krnlSVN.

Also the first post on the OS2World thread about OS/4 should contain the direct link to the release.

Resources on the WWW
is an official HTTP server, where you can get the latest OS/4 kernel releases and some useful utilities.

is a section on the Russian Underground/2, fully devoted to the Phoenix project (Russian only).

is an IRC channel where you can get support.

is a thread on the OS2World forum about OS/4.

Contacting developers
The most easy way to contact Phoenix is to join the #os2russian IRC channel on the original EFNet network.

There is no collaborative e-mail mailbox, but you may consider writing to the SU.OS2 Fidonet area... Hrm. Well, the IRC channel is the best option.

Also there is a technical forum at the Russian Underground/2, where you can try writing to, too.

Most of the dialogs in the IRC channel, RU/2 forum, or the echo conference are performed in Russian, but if you jump there in English, you will get a conversation.

Also there is a thread in the OS2World forum (which is in English), where you can get support, too.