Skip to main content.

About the Suite

The TinyKRNL Test Suite, part of Dazzle, is a combination of tools which allow testing TinyKRNL and/or its components, as well as debugging them. It is a combination of three tools:

The Test Suite has three uses, which are adapted to specific phases of the TinyKRNL development plan. It can be used as follows:

  1. While Phase 1 is still in progress, the Test Suite uses an image which must be built from a Windows 2003 Service Pack 1 download. This image boots into a 4MB micro-version of the Windows 2003 Service Pack 1 environment, made of the same components which are being targeted for TinyKRNL's Phase 1, plus the NT Boot Loader and a post-installation registry. At this stage, the Test Suite can be used in component testing mode, which replaces one Windows component with a TinyKRNL component, for the purpose of verifying wether or not the Test Suite Image can still boot to the Native Command Line Interface (NCLI) and provide the same functionality and stability as when the Windows component was being used.
  2. Once all Phase 1 components will be complete, then it will be unnecessary to use a Windows 2003 Service Pack 1 Installation Media, since all the files needed to boot into the NCLI will be implemented by the TinyKRNL project. At this step, the Test Suite can be used in full testing mode, which means that the suite will boot the OS directly for purposes of testing it directly, trying to load 3rd-party drivers, etc. During this step, Windows components will be dropped in and tested if they load/work, instead of vice-versa. For example, the Windows Network Architecture files (tcpip.sys, afd.sys, etc) will be dropped in and made able to load, then TinyKRNL's own versions will be developed.
  3. At all phases and times, the Test Suite can be used in debugging mode. This additional flag to the Test Suite script will launch WinDBG in an attempt to establish a Kernel Debugger connection with KQEMU, which will allow debugging of the OS or any individual component.

As you can see, the Test Suite is an integral part of the TinyKRNL development toolkit (Dazzle) and understanding how to use it is primordial to proper testing and debugging capabilities. Because TinyKRNL is not yet meant to run on real hardware until later phases, using the Test Suite will be the only way to actually test and use the OS for quite some time.

^ TOP

Setting up the Suite

If this is the first time that you are running the Test Suite, then you should write "test" by itself. The following dialog should then appear:

After pressing a key, the Test Suite should run:

You now need to setup your Test Suite by building the test image. To do so, follow the on-screen instruction and write "test install". The following dialog will then appear:

After writing "yes" to the first question, a second question will enquire about the legality of your download attempt. In some countries, you will require a valid Windows 2003 license in order to download the service pack, in others, this is not needed (since the download is public and cannot be used independently). You will need to check your country's laws before continuing. Unfortunately, until the end of Phase 1, if you are not legally entitled to downloading Service Pack 1, you cannot use the Test Suite. After writing "yes" to this second question, if applicable, you will be re-directed to a Microsoft page with more information on the download.

After obtaining the service pack executable, launch it with the -x parameter after the name. This will popup a dialog asking you where you would like to extract the files. The service pack will not be installed, only extracted. Once the files are extracted, launch the Test Suite again as instructed, with the path to the service pack files as a parameter, such as: "test install c:\sp1files". This will create a release of TinyKRNL, building all the files in the tree, then copy some files from the service pack. Once complete, the dialog window should show a status message resembling the following:

^ TOP

Using the Suite

To run the suite in component testing mode, simply write "test" followed by a space and the name of the component that you wish to test. For example, to try out the PCI Bus Driver, you would write "test pci". This will make a backup of the Windows driver, copy the TinyKRNL driver, and then launch the Test Suite.

To run the suite in full testing mode, only write "test current". Note that until Phase 1 is completed, this will merely launch a micro-sized Windows Server 2003 SP1 installation which will boot into NCLI. No TinyKRNL components will actually be used. After Phase 1 is completed however, this will launch the TinyKRNL OS using all the TinyKRNL components developed.

At any time, to run the suite in debugging mode, add "debug" as a parameter. For example, to test the PCI Bus Driver and launch WinDBG to connect to TinyKRNL, write "test pci debug". To test the entire OS, write "test debug".

^ TOP

Testing a Component

To test a component, say the PCI Bus Driver, open a Dazzle Window, then follow these steps:

  1. Write the name of the component on the command-line, such as "pci". This will build it. Make sure that there are no build errors.
  2. Write "test pci". The following should appear:


  3. After a short while, you should see KQEMU started up:

  4. If the component is not working properly, then you might see a bug check (Blue Screen Of Death/STOP Error), a black screen, or unresponsive keyboard input. If this happens, you can try debugging the component, which we will cover below.
  5. If everything seems to be working fine, try using some of the Native Command Line Interface (NCLI) commands (write "help" for a list), and see if they work properly. For a component like the PCI Bus Driver, some useful commands might be ones to dump the Device Tree or other hardware information.

^ TOP

Debugging the OS or a Component

If you are getting a bug check, black screen or any other sort of problem while booting TinyKRNL or one of its components, you can use WinDBG to try and debug the problem, while being able to set breakpoints, walk through source code and/or assembly, and view a myriad of other OS internals. To do this, follow the same steps as above, but add the parameter "debug" to step 2, so that the command becomes "test pci debug". Once this is done, you should see the same Dazzle information as previously shown, but a new instance of WinDBG should be launched:

If all goes well, then the window should expand and new information should appear on the Command Window:

Windows Server 2003 Kernel Version 3790 UP Free x86 compatible
Built by: 3790.srv03_sp1_rtm.050324-1447
Kernel base = 0x80800000 PsLoadedModuleList = 0x808a8e48
System Uptime: not available

Once the connection is fully complete, the following messages should appear:

Break instruction exception - code 80000003 (first chance)
*******************************************************************************
* *
* You are seeing this message because you pressed either *
* CTRL+C (if you run kd.exe) or, *
* CTRL+BREAK (if you run WinDBG), *
* on your debugger machine's keyboard. *
* *
* THIS IS NOT A BUG OR A SYSTEM CRASH *
* *
* If you did not intend to break into the debugger, press the "g" key, then *
* press the "Enter" key now. This message might immediately reappear. If it *
* does, press "g" and "Enter" again. *
* *
*******************************************************************************
nt!RtlpBreakWithStatusInstruction:
8081d97e cc int 3

At this point, you can start setting breakpoints and walking through kernel source code (if running on TinyKRNL's kernel). If you are only testing a component, then you will only be able to walk through that specific component's source code. You should set a breakpoint on the driver's DriverEntry function, which will make WinDBG break into your driver when it loads. After this, it should automatically display your driver's source code and you can walk through it just like in Microsoft Visual C/C++.

To test the entire OS, simply write "debug" after the test current command, ie.: "test current debug". If you need help using WinDBG, please refer to its documentation or the Microsoft Newsgroups and/or Support Groups. Do not ask WinDBG-specific questions to the TinyKRNL team, we will be unable to help.