Contents of /trunk/linterm_tools/fw_builder/make-nk/README

--- Copyrights, authors and stuff

This program is derived (but kind of heavily modified) from LinuxCE from Anders Larsen. You can download his version from http://www.alarsen.net/linux/. Parts of his code are based on Linux source code.

As you can see from the COPYING file, this program is GPL'ed. Do what you want with it, but keep it free. :-)

--- nk.bin generator

The Winterm devices normally run Windows CE. The BIOS bootstraps WinCE by reading a file called nk.bin, which basically contains a lot of data, some offsets (where to put it in RAM) and an entry point. It's actually not really hard to put Linux code in such a file, instead of a Windows kernel. And this is exactly what this tool does.

The big advantage of this approach, as opposed to replacing the whole Winterm BIOS with something else, is that it's pretty non-destructive. As long as the BIOS is still there, it's always possible to reflash the OS. You can put back WinCE, or of course you can install a newer Linux kernel. At least for now you'll need a DOS machine and a parallel cable to do this, we might be able to fix this later.

It consists of two files. boot.S is the little bootloader (derived from linux/arch/i386/boot/setup.S), make-nk.c is the file that combines the bootloader, a kernel and optionally a RAM-disk, into the nk.bin file.

Since boot.S is derived from in-kernel code and not from a regular bootloader, there could be some compatibility issues. Since the Winterm is in protected mode already when it jumps into the nk.bin entry point, we have to skip a few steps. Since setup.S is where Linux switches to protected mode, this is also where we should start. However, this means we can't do those BIOS calls anymore to detect memory, APM, that kind of things. (Actually, it is possible to return to real mode to do these calls, but for now we won't bother) For now, we'll live without them. APM is not our top priority (although the thing is supposed to know about both APM and ACPI!) and memory can be detected in other ways.

Anyway, compatibility issues can be there, after all this code puts a completely different version of setup.S together with any kernel. Fortunately it worked so far with at least some 2.4- and 2.6-kernels. We didn't try 2.2, but then again, those are a bit too old anyway.

See the help information for the make-nk command, it should be enough to get it to work. Don't try to flash the nk.bin file directly into the Winterm. It won't accept it anyway, use the bundle-tools to pack it into a Winterm firmware image. You can download bundle-tools from our site. You can also get more information about building suitable kernels from there.


Happy hacking!

Wilmer van der Gaast <wilmer@gaast.net>
http://winterm.gaast.net/
1	--- Copyrights, authors and stuff
2
3	This program is derived (but kind of heavily modified) from LinuxCE from Anders Larsen. You can download his version from http://www.alarsen.net/linux/. Parts of his code are based on Linux source code.
4
5	As you can see from the COPYING file, this program is GPL'ed. Do what you want with it, but keep it free. :-)
6
7	--- nk.bin generator
8
9	The Winterm devices normally run Windows CE. The BIOS bootstraps WinCE by reading a file called nk.bin, which basically contains a lot of data, some offsets (where to put it in RAM) and an entry point. It's actually not really hard to put Linux code in such a file, instead of a Windows kernel. And this is exactly what this tool does.
10
11	The big advantage of this approach, as opposed to replacing the whole Winterm BIOS with something else, is that it's pretty non-destructive. As long as the BIOS is still there, it's always possible to reflash the OS. You can put back WinCE, or of course you can install a newer Linux kernel. At least for now you'll need a DOS machine and a parallel cable to do this, we might be able to fix this later.
12
13	It consists of two files. boot.S is the little bootloader (derived from linux/arch/i386/boot/setup.S), make-nk.c is the file that combines the bootloader, a kernel and optionally a RAM-disk, into the nk.bin file.
14
15	Since boot.S is derived from in-kernel code and not from a regular bootloader, there could be some compatibility issues. Since the Winterm is in protected mode already when it jumps into the nk.bin entry point, we have to skip a few steps. Since setup.S is where Linux switches to protected mode, this is also where we should start. However, this means we can't do those BIOS calls anymore to detect memory, APM, that kind of things. (Actually, it is possible to return to real mode to do these calls, but for now we won't bother) For now, we'll live without them. APM is not our top priority (although the thing is supposed to know about both APM and ACPI!) and memory can be detected in other ways.
16
17	Anyway, compatibility issues can be there, after all this code puts a completely different version of setup.S together with any kernel. Fortunately it worked so far with at least some 2.4- and 2.6-kernels. We didn't try 2.2, but then again, those are a bit too old anyway.
18
19	See the help information for the make-nk command, it should be enough to get it to work. Don't try to flash the nk.bin file directly into the Winterm. It won't accept it anyway, use the bundle-tools to pack it into a Winterm firmware image. You can download bundle-tools from our site. You can also get more information about building suitable kernels from there.
20
21
22	Happy hacking!
23
24	Wilmer van der Gaast <wilmer@gaast.net>
25	http://winterm.gaast.net/