Contents of /trunk/linterm_tools/fw_builder/bundle-tools/README

--- Bundle tools

These are some tools to read, edit and create bundles, that can be used to update firmware of WYSE (and compatible) Winterm devices. Note that I'm not related to WYSE in any way. I found all this information by carefully looking at firmware images, and a bit of trial and error.

Also, use these tools with care. Although we think it's hardly possible to leave your Winterm in a state that can't be repaired if you don't touch the BIOS. As long as the BIOS works, you can always flash in new software through the parallel cable. Just be careful to not upload a wrong BIOS (so no Leo BIOS in a Midway device, etc.). We never tried this, we don't want to. (Although this can possibly be fixed too. It's possible to get out the NOR chip that keeps the BIOS, so if you got the hardware for it you can reflash it by hand.)

Just always be careful. And if something breaks (it didn't happen to us so far) we can't be held responsible. It's unlikely to happen if you're careful, but never say never.

--- Compilation HOWTO

First of all, download a bundle that belongs to exactly your hardware. For WYSE models, you can get it from:

http://www.wyse.com/serviceandsupport/support/downloads.htm

If you got a clone, you'll have to look somewhere else. First of all, you need this file to compile fwpack. Later, you will need it to get out a BIOS. The upgrade files are usually put together in a (self-extracting) zip-file. Unpack it and look for the biggest file. This is probably the bundle. It should be somewhere around 8 or 16 MBytes, depending on the amount of flash your device has. The file usually has a WYE extension (or CPQ for Compaq devices). Put this file in the bundle-tools source tree.

Now, if the filename of the bundle is correct, you should be able to run make, and everything should work. If not, extract_head.pl will complain, and hopefully you'll be able to fix what's wrong. The tool will try to find the bundle by itself, if it fails you can try to run the tool by hand, giving the name of the example bundle as an argument. After that, run make again and everything should work.

In case you wonder why running this tool is necessary, the tool extracts the headers from an existing firmware bundle. They're slightly different for each model, so it's best to get them from a file that is known to work on your machine. Also, we don't want to include original data with our sources, since we don't own the copyrights.

BTW, note that we didn't test the tools too much for portability. Endianess and 32-bit vs. 64-bit shouldn't be a problem, but we didn't test many operating systems. If you're not on Linux or BSD, YMMV. But when porting Linux to a Winterm, you're most likely running Linux anyway, right? :-)

--- Preparing for first use

Before creating your first image, you now have to extract some files from the original image. This is what you should use fwextract for. It's probably a good idea to read the help information for this program now.

At least one file is really important, it's the file that contains the BIOS. On Midway platforms it's usually called mid_code. You can easily find the file by looking for a file with BiosFlag set to 00010000, and exactly 256KB (40000 in hex) bytes long. It's usually the first file in the image. It's probably a good idea to also extract the file called "k". This file contains some magic bytes so the update tool can recognize if the image is meant for the right platform. Although the contents of this file is repeated in the headers, it's possible that the WinCE-based upgrade tool depends on it. And with the file being only 20 bytes long, it can't hurt to include it.

Optionally, you can also extract poweron.bmp, but most likely you'll prefer to make your own start-up image (or use ours), after all that Windows CE logo won't make a lot of sense anymore.

Put all these files together, wherever you want to have them. Now you might want to put these files into a bundle together with a bzImage and optionally an initrd. This is, however, not what you should do.

The WYSE BIOS doesn't know about Linux. Not in the 3000 series, at least. It's made to boot Windows CE, and just Windows CE. So now you should put Linux code into a file that can be loaded by a WinCE-loader. This is what make-nk does. It puts a bzImage, a bootloader and optionally an initrd together in a file called nk.bin. The BIOS will look for this file when booting, load it into memory and jump into the bootloader.

make-nk is another tool that isn't completely finished yet, at the time of writing. There are some minor issues with memory detection that keep us from releasing it. As soon as we fix these issues, we'll put that stuff on-line too. Until then, please be just a bit more patient.

But well, let's at least finish these instructions first. ;-)

--- Making an image

Now that we got our Linux code in the nk.bin file, it's time to create a bundle from it. In this bundle, two things are absolutely necessary: a BIOS, and the nk.bin file we just created. It's probably best to also include a correct k file for your platform.

Including a poweron.bmp is not necessary. If you leave it out, you'll get the typical Win95-green screen when booting. We don't know exactly how big this file can be, it doesn't seem to be very restricted. Most likely it should be at most 640x480 pixels, and at most 8-bit colours. RLE compression is recommended, since flash space is too precious to waste on a picture that is (hopefully) shown for only a couple of seconds.

To create an image, use fwpack. Again, it's probably best to first read the help information. In short, the program takes at least two arguments. First of all, the filename of the bundle that should be created. After that, name all the files that should be included in the bundle. Important detail is that you have to specify the BIOS first. The BIOS file always gets a special flag, because it will be flashed into the special BIOS chip instead of the standard 8MB NAND flash memory. After the BIOS, specify the other files, in any order you want. I usually put the in the order: "BIOS k nk.bin poweron.bmp". Any order should work though.

If everything works, you should get an output similar to this:

tosca~/winterm$ upg/fwpack linux.img fwbase/mid_code fwbase/k nk.bin fwbase/poweron.bmp 
fwpack - Generate WYSE Winterm firmware bundles

Checking all files and building index.... Done!
Building for machine type: 03 02 01 01
Calculating file offsets...
Expected image size: 1538596
Now creating image headers and index... Done!
Writing the files...
  mid_code
  k
  nk.bin
  poweron.bmp
End checksum of file is 0, good!

--- Uploading the image

Congratulations, you just wrote your first Linux image! Now the last step is to upload it to your Winterm. As long as WinCE is still on it, there are two ways to do this. First way is to first put your image at some place reachable over FTP. Note that for WinCE upgrades, just this image is not enough. It's best to unzip the whole archive you downloaded from WYSE and replace the big bundle file with the one you just created. You don't have to change anything else. The other files will be read, but they don't contain anything like a size or checksum, so they're fine the way they are.

After that, boot your Winterm and go to the configuration menu (press F2 when the session chooser opens). Go to the Upgrade tab and fill in the right information so it can reach the files over FTP. Start the process and wait. If everything works, it should erase the flash and put your image on it! It should reboot, and depending on your configuration, you will see Linux booting on screen or on some serial terminal. See the make-nk documentation for more information about this.

Obviously, as soon as WinCE is gone, you can't perform this kind of upgrade anymore. To do another upgrade, you'll need a parallel Laplink cable, a machine that runs DOS, and the XFER.EXE tool, which you can download from the WYSE website. (Also, possibly you might need to first flash the MID.BIN/LEO.BIN file, in case you were running an old version of WinCE. We're not sure about this though. If you're not sure, it can't hurt to do this first.) It's probably best to read the documentation from WYSE about this.

Only one thing I can add to this document: On some systems the xfer tool just won't work. The Winterm hangs during the boot process, all you see is the poweron.bmp. Just close xfer and the Winterm will boot again, but a firmware upgrade is probably not going to happen.

We don't know why this happens exactly. Possibly the tool doesn't work on faster machines. I tried it on three machines now, and it worked only on older (slower?) machines. So if you have problems with this upgrade method, just try to find an older PC. I usually use my P2-350 for it, works like a charm.

Hopefully this is enough to get you started. Happy hacking!


Wilmer van der Gaast <wilmer@gaast.net>
http://winterm.gaast.net/
1	--- Bundle tools
2
3	These are some tools to read, edit and create bundles, that can be used to update firmware of WYSE (and compatible) Winterm devices. Note that I'm not related to WYSE in any way. I found all this information by carefully looking at firmware images, and a bit of trial and error.
4
5	Also, use these tools with care. Although we think it's hardly possible to leave your Winterm in a state that can't be repaired if you don't touch the BIOS. As long as the BIOS works, you can always flash in new software through the parallel cable. Just be careful to not upload a wrong BIOS (so no Leo BIOS in a Midway device, etc.). We never tried this, we don't want to. (Although this can possibly be fixed too. It's possible to get out the NOR chip that keeps the BIOS, so if you got the hardware for it you can reflash it by hand.)
6
7	Just always be careful. And if something breaks (it didn't happen to us so far) we can't be held responsible. It's unlikely to happen if you're careful, but never say never.
8
9	--- Compilation HOWTO
10
11	First of all, download a bundle that belongs to exactly your hardware. For WYSE models, you can get it from:
12
13	http://www.wyse.com/serviceandsupport/support/downloads.htm
14
15	If you got a clone, you'll have to look somewhere else. First of all, you need this file to compile fwpack. Later, you will need it to get out a BIOS. The upgrade files are usually put together in a (self-extracting) zip-file. Unpack it and look for the biggest file. This is probably the bundle. It should be somewhere around 8 or 16 MBytes, depending on the amount of flash your device has. The file usually has a WYE extension (or CPQ for Compaq devices). Put this file in the bundle-tools source tree.
16
17	Now, if the filename of the bundle is correct, you should be able to run make, and everything should work. If not, extract_head.pl will complain, and hopefully you'll be able to fix what's wrong. The tool will try to find the bundle by itself, if it fails you can try to run the tool by hand, giving the name of the example bundle as an argument. After that, run make again and everything should work.
18
19	In case you wonder why running this tool is necessary, the tool extracts the headers from an existing firmware bundle. They're slightly different for each model, so it's best to get them from a file that is known to work on your machine. Also, we don't want to include original data with our sources, since we don't own the copyrights.
20
21	BTW, note that we didn't test the tools too much for portability. Endianess and 32-bit vs. 64-bit shouldn't be a problem, but we didn't test many operating systems. If you're not on Linux or BSD, YMMV. But when porting Linux to a Winterm, you're most likely running Linux anyway, right? :-)
22
23	--- Preparing for first use
24
25	Before creating your first image, you now have to extract some files from the original image. This is what you should use fwextract for. It's probably a good idea to read the help information for this program now.
26
27	At least one file is really important, it's the file that contains the BIOS. On Midway platforms it's usually called mid_code. You can easily find the file by looking for a file with BiosFlag set to 00010000, and exactly 256KB (40000 in hex) bytes long. It's usually the first file in the image. It's probably a good idea to also extract the file called "k". This file contains some magic bytes so the update tool can recognize if the image is meant for the right platform. Although the contents of this file is repeated in the headers, it's possible that the WinCE-based upgrade tool depends on it. And with the file being only 20 bytes long, it can't hurt to include it.
28
29	Optionally, you can also extract poweron.bmp, but most likely you'll prefer to make your own start-up image (or use ours), after all that Windows CE logo won't make a lot of sense anymore.
30
31	Put all these files together, wherever you want to have them. Now you might want to put these files into a bundle together with a bzImage and optionally an initrd. This is, however, not what you should do.
32
33	The WYSE BIOS doesn't know about Linux. Not in the 3000 series, at least. It's made to boot Windows CE, and just Windows CE. So now you should put Linux code into a file that can be loaded by a WinCE-loader. This is what make-nk does. It puts a bzImage, a bootloader and optionally an initrd together in a file called nk.bin. The BIOS will look for this file when booting, load it into memory and jump into the bootloader.
34
35	make-nk is another tool that isn't completely finished yet, at the time of writing. There are some minor issues with memory detection that keep us from releasing it. As soon as we fix these issues, we'll put that stuff on-line too. Until then, please be just a bit more patient.
36
37	But well, let's at least finish these instructions first. ;-)
38
39	--- Making an image
40
41	Now that we got our Linux code in the nk.bin file, it's time to create a bundle from it. In this bundle, two things are absolutely necessary: a BIOS, and the nk.bin file we just created. It's probably best to also include a correct k file for your platform.
42
43	Including a poweron.bmp is not necessary. If you leave it out, you'll get the typical Win95-green screen when booting. We don't know exactly how big this file can be, it doesn't seem to be very restricted. Most likely it should be at most 640x480 pixels, and at most 8-bit colours. RLE compression is recommended, since flash space is too precious to waste on a picture that is (hopefully) shown for only a couple of seconds.
44
45	To create an image, use fwpack. Again, it's probably best to first read the help information. In short, the program takes at least two arguments. First of all, the filename of the bundle that should be created. After that, name all the files that should be included in the bundle. Important detail is that you have to specify the BIOS first. The BIOS file always gets a special flag, because it will be flashed into the special BIOS chip instead of the standard 8MB NAND flash memory. After the BIOS, specify the other files, in any order you want. I usually put the in the order: "BIOS k nk.bin poweron.bmp". Any order should work though.
46
47	If everything works, you should get an output similar to this:
48
49	tosca~/winterm$ upg/fwpack linux.img fwbase/mid_code fwbase/k nk.bin fwbase/poweron.bmp
50	fwpack - Generate WYSE Winterm firmware bundles
51
52	Checking all files and building index.... Done!
53	Building for machine type: 03 02 01 01
54	Calculating file offsets...
55	Expected image size: 1538596
56	Now creating image headers and index... Done!
57	Writing the files...
58	mid_code
59	k
60	nk.bin
61	poweron.bmp
62	End checksum of file is 0, good!
63
64	--- Uploading the image
65
66	Congratulations, you just wrote your first Linux image! Now the last step is to upload it to your Winterm. As long as WinCE is still on it, there are two ways to do this. First way is to first put your image at some place reachable over FTP. Note that for WinCE upgrades, just this image is not enough. It's best to unzip the whole archive you downloaded from WYSE and replace the big bundle file with the one you just created. You don't have to change anything else. The other files will be read, but they don't contain anything like a size or checksum, so they're fine the way they are.
67
68	After that, boot your Winterm and go to the configuration menu (press F2 when the session chooser opens). Go to the Upgrade tab and fill in the right information so it can reach the files over FTP. Start the process and wait. If everything works, it should erase the flash and put your image on it! It should reboot, and depending on your configuration, you will see Linux booting on screen or on some serial terminal. See the make-nk documentation for more information about this.
69
70	Obviously, as soon as WinCE is gone, you can't perform this kind of upgrade anymore. To do another upgrade, you'll need a parallel Laplink cable, a machine that runs DOS, and the XFER.EXE tool, which you can download from the WYSE website. (Also, possibly you might need to first flash the MID.BIN/LEO.BIN file, in case you were running an old version of WinCE. We're not sure about this though. If you're not sure, it can't hurt to do this first.) It's probably best to read the documentation from WYSE about this.
71
72	Only one thing I can add to this document: On some systems the xfer tool just won't work. The Winterm hangs during the boot process, all you see is the poweron.bmp. Just close xfer and the Winterm will boot again, but a firmware upgrade is probably not going to happen.
73
74	We don't know why this happens exactly. Possibly the tool doesn't work on faster machines. I tried it on three machines now, and it worked only on older (slower?) machines. So if you have problems with this upgrade method, just try to find an older PC. I usually use my P2-350 for it, works like a charm.
75
76	Hopefully this is enough to get you started. Happy hacking!
77
78
79	Wilmer van der Gaast <wilmer@gaast.net>
80	http://winterm.gaast.net/