NetWinder Recovery HOWTO
Version 0.06
Thu Aug  6 02:30:15 EDT 1998

Written by: Stanislav N. Vardomskiy (stany at pet dot ml dot org)

This document describes how to restore your Corel NetWinder to operational
capability after you have either destroyed your boot partition and can not
log in, or you have deleted the kernel and can not boot.

NOTE:  Nor this document, nor the techniques described in it are supported
or endorced by Corel Corporation at the time of the writing.  They are,
however, beleived to be correct.  Never the less, excercise common sense
before performing any sort of an action.  			//Stany

----------------------------------------------------------------------------

Table of Contents

1.0 Introduction
	1.1 Why this HOWTO?
	1.2 What will we need?
2.0 Filesystem recovery
	2.1 Disk layout
	2.2 A bit about firmware
	2.3 Disk converter
	2.4 NFS, and creative abuses of it
	2.5 Linux dhcpd
	2.6 tftpd, and getting it
	2.7 NFS caveats
	2.8 What to do now?
3.0 Conclusion
4.0 Acknoveledgements
5.0 Copyright and other legal blurb


----------------------------------------------------------------------------

1.0 Introduction

	1.1 Why this HOWTO?

  In theory I could put lots of interesting things as the reasons, like
desiring to make the world a better place to live, and what, but in
reality,  the explanation is simple.  I have been one of the first five
people outside of (then) Corel Computer Corporation to get my hands on the
NetWinder, and since I had some chances to play with it, and use it for
serious tasks.  In process I have damaged the contents of the hard drive
in in-numerous ways and in-numerous times, and as a result, eventually too
got fed up with going back into Corel Computer Corporation to have the
patient and understanding folks there help me fix my own screw-ups.  
 
   It seems that I was the first person who have trashed a root filesystem
of the NetWinder outside of Corel, it was a weekend, and there was no easy
way to get it fixed without external help.  So I had to get it going myself. 

This is where the story begins....

	1.2 What will we need?

   We will need a NetWinder and another computer running Linux.  You must
have root on the other Linux box, it must be connected to the Internet at
least intermittently, and it must have a network card.  

You will need Internet access in order to download the root filesystem
image and firmware updates from ftp.netwinder.org.  Network card will be
necessary in order to connect to the NetWinder.  Root is good at all times
;-)


2.0 Filesystem recovery

	2.1 Disk layout

  The partitioning of the NetWinder depends on the firmware.
System with firmware rev 1.3pl3 or earlier are partitioned in this way:

 /dev/hda1 - 4 meg partition containing the kernel
 /dev/hda2 - root filesystem of the Linux.

  If you have 3 partitions, then /dev/hda3 is swap.  Traditionally it is
in the vicinity of 64 or so megs.  if you have a large disk, and there are
4 partitions, then chances are that /dev/hda4 is the swap, and /dev/hda3
is another Linux partition.

  Now, if your firmware release is 1.4 or higher(mostly the Debian people
who have access to Alan DeKok's Netwinder, and anyone else who have upgraded), 
then the partitions are set up this way:
 /dev/hda1 - root filesystem

  If there are 2 partitions, then /dev/hda2 is swap.  If there are 3,
then /dev/hda2 can be another Linux partiton, and /dev/hda3 can be swap.  

  The reason I go into such detailes about the partitioning, is because
the firmware expects to find the root filesystem and the kernel in certain
places.  If you have accidentally screwed up your filesystem table, and
recreated it not the way the firmware expects, then the firmware will die
with errors like: 
[NeTTrom] IDE disk boot failure
or 
[NeTTrom] Possible HD data corruption or O/S not available
or even 
[NeTTrom] Master boot record does not contain executable code

  Needless to say, this will make booting from the hard drive of your
NetWinder a little bit inefficient.


	2.2 A bit about firmware

  Firmware is what glues the NetWinder together, and what allows the box
to boot.  It was written by San Mehat, and is stored in a 1 meg flash ROM,
on the motherboard of the NetWinder.  Because the ROM is flashable, it is
possible to do upgrades of the firmware on the fly, once the machine have
booted.  It has to be noted, though, that the first 64 K of firmware are
critical - if they are overwritten, the process of rewriting new firmware
will become painful - a special procedure, called j-tag will have to be
utilized to write the raw code into the ROM.  In reality this procedure is
not possible in normal home conditions, but if your home has
oscilloscopes, ROM burners, ROM writers and other interesting devices, I
will be very interested if you have managed to do something ;-)

  Different revisions of the firmware have provided different levels of
functionality.  Before firmware revision 1.0, all of the firmwares were
not versioned, but dated.  Revision 1.0 had a notice about the NetWinder
being a special loan to Ottawa Carleton Linux Group, revision 1.2 had
support for 2 IDE hard drives finalized and working, and revision 1.3pl1
had finally permitted one to boot from non NT DHCP server.  Revision
1.3pl3 have finally implemented a bootp fix.  

  Revision 1.4 is a developement revision of the firmware.  Rev 1.4c  
includes finalized support for multiple kernels, and a rudimentary boot
manager.  1.4d also includes some sdram speedups.  

 I have seen an Alpha of 1.5 firmware.  It allowes one to set up a 
hardware eithernet address of the router in firmware, which allowes one 
to boot off a networ k server that is not on the same subnet.  Also it 
implements a number of firmware wariables, similar to the ones on Sun 
OpenBoot PROM.  In fact anyone familiar with Sun firmware should be 
right at home.  Also there are plans for a firmware based debugger 
announced today, that would allow one to debug the kernel and actually 
find out why one got the dreaded GLAP! in NetWinder kernel.    
(GLAP! is the NetWinder specific error message that is outputted when 
kernel is really confused and crashes as a result)

  Even though rev 1.4 or 1.5 firmware is not generally available to 
public, and is not yet shipping, I guess I should tell a little bit more 
about the boot manager.  

  The boot manager now is rather utilitarian, but it works, and it works
well.  In /boot directory there resides a file called /boot/nettrom.cfg
In the nettrom.cfg, one per line there are the names of the boot kernels.
I suppose that the best will be an example:

root@pooga:/boot[4]# uname -a
Linux pooga.research.xxxxx.net 2.0.31 #522 Tue Jul 21 10:09:05 EDT 1998 sa110
root@pooga:/boot[5]# ls 
nettrom.cfg	vmlinux		vmlinux.test	vmlinux_elf
root@pooga:/boot[6]# cat nettrom.cfg
vmlinux
vmlinux_elf
vmlinux.test
root@pooga:/boot[7]#

The boot manager loads up the minikernel from flash, and then if
booting from disk, mounts the filesystem read-only.  It reads the
/bin/nettrom.cfg, and presents the user with a list of kernels in
nettrom.cfg.  A feature is now in works that will permit firmware to
search the hard drive for kernel, and boot from it is now in work.  A use
for this occures when one forgets to move the compiled kernel into /boot
and increment the nettrom.cfg.  

If you have 1.4 version firmware, and you have upgraded your disk image, 
do not forget to create your nettrom.cfg file - otherwise you will 
confuse the firmware, like it have happened to me a few times.

Initrd support (to allow one to place a compressed tiny filesystem image
into a firmware) is in progress, and will be announced soon.  Potential
uses for such disk-less machines, that boot from the ROM are plenty:
secure firewalls, that log to remote machines, routers, and many other
things.  Also it is nice to know that if you trash your drive, you can
boot from the ROM and fix it, a la Mac SE, that had System 6.07 in 
firmware. Latest estimates show that there will be about 670K of unused 
space in firmware - enough for mount, fsck, and vi.

  Please note that even though the firmware does support connection of the
second hard drive, and will recognize it fine, as will Linux, opening the
case will void the warranty, especially if you try to solder something
onto the motherboard.  But if you are an adventurous type, go for it, just
do not sue me afterwards.  

	2.3 Disk converter.

  I suppose that the more politically correct way to call this device is
"disk adapter".  It is a tiny board that allows one to connect the laptop
form-factor hard drives to the IDE connectors of the "grown-up" machines.
Even though opening the NetWinder voids your warranty, if you are really
desperate, and have nothing to regret, you can always open the case
(careful - those screws are long, and if the screwdriver is not proper, by
the time you are through opening the case, the screws will be useless.  I
know for a fact that Andrew Mileski uses an electric screwdriver in order
to open the cases ;-), take out the drive, and connect it to the IDE or
EIDE bus of your Intel Linux PC.  Once you have done it, it is possible to
mount the filesystems, format the partitions, and otherwise modify the
drive.

  NOTE: these disk adapters are really dumb devices, with usually no
guidance rails or anything to differentiate which way to plug the "2.5
drive in.  Make sure you plug the drive in the right way, because
otherwise you will put 12V across data 4 and data 7, which generally leads
to magic smoke escaping from the drive.  Please be careful.  

  Once again I want to stress that even though it it possible to do, you
always risk misjudging, shorting or scratching something, damaging the
computer and loosing the warranty all at the same time.  Please exercise
caution.

	2.4 NFS, and creative abuses of it.

  Unless your firmware is damaged, in which case you should take your
'winder in for repair, the firmware will always allow you to boot from the
network if asked politely.  If the revision of the firmware you have is
newer then 1.0 (1.1+), you have to hold "shift" (or any other key) down 
during the partition check in order to have the system query you what do 
you want to boot from.  My prompt looks like this:

[...]
Partition check:
 hda:  hda1 hda2 hda3 hda4 
[NeTTmk-linux] Enter netconfig method (dhcp/static/disk/rescue) ->

Static option doesn't work with the firmware 1.3pl1.  Eventually it will
be implemented in some form or other. 

Disk allows one to read in the boot kernel from disk.

DHCP and Rescue options are similar - both query DHCP server and use the
obtained IP address and gateway, but while rescue is automated and attempts
to connect to the rescue server and download the new image of your hard
drive (I am taking wiped drive), dhcp obtains the IP and gateway, and asks
the next question:

DHCP->[DISK][SEND][RECV][PROCESS][OFFER][REQ][SEND][RECV][PROCESS][ACK]
[NeTTmk-linux] IP Address -> 10.1.73.65
[NeTTmk-linux] Netmask    -> 255.255.255.0
[NeTTmk-linux] Broadcast  -> 10.1.73.255
[NeTTmk-linux] Boot Server->
[NeTTmk-linux] Boot File  ->
[NeTTmk-linux] Boot Path  ->
[NeTTmk-linux] Enter kernel retrieval method (tftp/disk) ->

  As you can see, DHCP server have replied back, providing the 'winder
with required network parameters.  This NT DHCP server is dumb, and as a
result it did not provide any extra information.  

	2.5 Linux dhcpd

  NOTE: If you firmware version is older then 1.3pl1, then you have to
upgrade to at least 1.3pl1 to use Linux DHCP - Corel people decided that
because there is way more networks with NT dhcp server (which is broken in
weird and wonderful ways), then the NT dhcp server should be the first one
to be fully supported.  But if your network has a Linux DHCP server and NT
DHCP server at the same time, and the 'winder receives two replies at the
same time, firmware is smart enough to pick the Linux DHCP reply.

  Of course Linux has a native DHCP daemon - how else would this have
been?  It is available from many FTP sites around the world that mirror
ftp.isc.org, or from ftp://ftp.isc.org/isc/dhcp/

  After you have unpacked it, read the instructions, compiled and
installed it, it is a good idea to read the manual.  Linux people who use
Red Hat may be faster off by downloading dhcp-2.0b1pl0-2.rpm from their
favorite mirror.  

  The following modifications to the conffile are courtesy of San Mehat:

  In the subnet declaration, add the options root-path line as follows:
(here is mine to illustrate) 

          subnet 10.1.0.0 netmask 255.255.0.0 { 
          range 10.1.54.199 10.1.54.202; 
          option broadcast-address 10.1.255.255; 
          option routers router.corelcomputer.com; 
          option root-path "10.1.54.7:/vncroot"; 
        } 
      } 

 In my case, I've used a hardcoded MAC for the host declaration...  You
don't need to do this but here is what I did anyways: 

      host san { 
        hardware ethernet 0:10:57:00:10:00; 
      fixed-address san.corelcomputer.com; 
      filename "vmlinux_vnc.rev4"; 
      server-name "10.1.54.7"; 
      } 

  So this is how one sets up ones DHCP according to the word from one of
the linux.gods.   ;-) 

  Now, if you use Linux DHCP, the other 3 fields on DHCP reply are filled
in:

DHCP->[DISK][SEND][RECV][PROCESS][OFFER][REQ][SEND][RECV][PROCESS][ACK]
[NeTTmk-linux] IP Address -> 10.1.54.65
[NeTTmk-linux] Netmask    -> 255.255.255.0
[NeTTmk-linux] Broadcast  -> 10.1.54.255
[NeTTmk-linux] Boot Server-> 10.1.54.7
[NeTTmk-linux] Boot File  -> vmlinux_vnc.rev4
[NeTTmk-linux] Boot Path  -> 10.1.54.7:/vncroot

	2.6 tftpd, and getting it.

  But now you have choice again.  If you will select tftp, 'winder will
send a tftp request, and attempt to read and load the kernel from the tftp
server.  UNIX tftp daemon source code is available from
ftp://ee.lbl.gov/tftpd-1.2.tar.Z, it is trivial to compile and install
under Linux, and as with firmware, kernels are available on
ftp.netwinder.org

  If you select disk, the machine will boot from the HD, but using the
supplied parameters.  Unfortunelly on boot-up rc scripts will reconfigure
the network card, so in theory using DHCP is not overly useful out of the
box.  With some creative editing if S10network, you can use DHCP for IP
allocation.

  If you select NFS, next thing that will be asked is:
[NeTTmk-linux] Enter root partition location (disk/nfs) -> nfs
[NeTTmk-linux] Enter NFS root server -> 10.1.73.96
[NeTTmk-linux] Enter NFS root path   -> /exports/netwinder

  Here I have replied to the firmware queries with IP address of the NFS
server, and NFS path where the root image of the drive is stored.

  After this the machine mounts the kernel, and boots from the filesystem
specified.  

	2.7 NFS caveats

  The following are a few advises I have regarding setting up NFS root
server for NetWinder:

  The best way to set up NFS if to read the NFS how-to available in many
places including http://sunsite.unc.edu/pub/Linux/docs/

  Exports file should have "no_root_squash" so that the filesystem will be
modifiable by the 'winder processes once the 'winder have booted. 

  The best way I have found to specify the IP of the winder, is to race to
the NFS server right after the 'winder gotten the DHCP reply, and modify
the /etc/exports.  A quick kill -HUP of mountd and nfsd later I was racing
back to the 'winder to specify NFS server.

  Among the problems that you will experience, there will be two related
to the filesystem.  After you have downloaded the root image from
ftp.netwinder.org, and uncompressed it somewhere convenient, you will have
to modify etc/fstab of the image so that / is mounted over NFS and is not
checked by fsck on start-up:

10.1.73.96:/exports/netwinder   /       nfs     defaults,noauto 0 0

is the entry I have.  Another problem you might encounter is hanging of
the 'winder after the tulip card have been initialized.  This is caused by
the etc/rc.d/rc3.d/S10network script attempting to reinitialize the
network cards.  The best way I have found to deal with this is just by
commenting out the loop that checks ifconfig-et? and configures the cards.

	2.8 What to do now?
  
  Well, format your /dev/hda2, and uncompress the root image into it.
Then try booting from your new filesystem.  If your kernel was shot, and 
your firmware is older then 1.4, dd it into /dev/hda1:

dd if=./vmlinux of=/dev/hda1 seek=1

  If you live on the edge and close to Corel Computer (ie: you have 
upgraded the firmware), then format /dev/hda1, mount it, uncompress the 
image onto it, grab a kernel from ftp.netwinder.org, and put it into 
/boot  Do not forget to edit the nettrom.cfg accordingly.  


3.0 Conclusion
  
  I hope that this have been useful to you.  If it was not, I humbly
apologize, and hope that you will be able to write your own, better
document.  

"Our product is perfect.  The problem must be you" --Dogbert (Scott Adams)


4.0 Acknowelegements

  Big thank you goes to San, Zac, Andrew, Pat, Eric, Alan, and Corel
Computers division of Corel Corporation - you all have done a great job.

  Also huge thank-you to all the people who maintain LDP, and write FAQs,
HOWTOs and whatnot else - you all are invaluable, and are a great source
of information.  If not for you, UNIX in general and Linux in particular
would have been a hell of a lot harder.

  San Mehat and Eric LaForest have proof-read this howto, and have both
contributed valuable information: San about the DHCP setup under Linux,
and Eric about the dangers of plugging the drive in backwards into the
converter board.

  A special thank-you goes to Pavel Tkatchouk - your messages on netwinder
lists have introduced me to the wonders of procmail.

  Lastly, huge thank-you to everyone I have forgotten - it is rather late,
so my brain is a mush. 8-(


5.0 Copyrights and other legal blurb

  This document is Copyright 1998 by Stanislav N. Vardomskiy and is
distributed under the terms of GPL.  If you want to distribute this as a
part of a book, I allow this with one condition: I would like an
autographed copy.  If you would like to distribute it on a CD-ROM, I
would appreciate getting a copy.  In other words: it is easy to bribe me,
and I always like presents ;-)

  No warranty is expressed or implied. If you trash your 'winder, please
do not hold me responsible.  Content might settle during shipment.  One
size fits all.  Not for use in mission critical environment.  Misuse might
lead to loss of human life.  By reading this document you relief me from
any and all legal persecution on your part.  Beta Version - Not for use in
actual combat environment.  They will listen to Reason.  Standard
disclaimers apply.  A fault-tolerant computer company can recover from my
opinions.  Have a nice day.  If you do not believe me, look it up. 
Caution, blade is sharp.  Keep out of children.  No, I do not live in 
fantasy, I only work there.

  All trademarks mentioned are acknoveledged as property of their
respective owners.  I do not associate with Corel Corporation in any way,
shape or form, and do not speak for my employer, who ever it may be.