
                          lphdisk release 0.9.1
                            February 12, 2000
                   Patrick D. Ashmore <pda@procyon.com>
                      Alex Stewart <alex@foogod.com>

===============================================================================

1. What is lphdisk?
2. How do I install/use lphdisk?
3. Do I need lphdisk to use hibernation with Linux?
4. What kind of laptops will lphdisk work with?
5. About the Artistic License

1. What is lphdisk? 
-------------------

lphdisk (pronounced "elf-disk")

This utility is intended to be the Linux equivalent of the DOS-only utility
"PHDISK.EXE" from Phoenix. This utility prepares and formats the hibernation
partition for notebook computers that use Phoenix NoteBIOS. Once this partition
has been prepared, it can be used with the BIOS's APM Suspend-To-Disk feature.

Note that one does not need this utility to be able to take advantage of
the Suspend-To-Disk feature of these Phoenix NoteBIOS laptops. Once the
hibernation partition is prepared, either from the DOS utility PHDISK.EXE that
Phoenix provides, or lphdisk, it can be used to suspend a machine's memory to
disk. 

This utility was created for two reasons. For the longest time Linux users
had to boot off of a DOS floppy and use Phoenix's buggy PHDISK.EXE program
to prepare their hibernation partition. True, this isn't a concern for most
users since they only have to do it once. It's a fire-and-forget sort of thing.
However, if they ever upgraded their memory, or replaced/repartitioned their
hard drive, they would have to once again dig out the DOS PHDISK.EXE. 

The second reason is that the company I worked for at the time I started this
program (Tuxtops) sold laptops with Linux, and having to involve DOS in our
laptop build process greatly slowed things down. The entire build process was
much faster and less error prone if it was done in a single pass with Linux.

There is sort of a third reason (or at least there was at the time). PHDISK.EXE
was somewhat buggy. Running it on a system that you had already prepared other-
wise was somewhat dangerous. You risked having PHDISK.EXE nuke preexisting
partitions (FAT or ext2, it didn't matter), create partitions with bad or
overlapping boundaries, or partitions that simply ran off the end of the disk.
Heck, to this date MicroSoft's own FDISK program is full of bugs... bugs that
have been around since the days of DOS. Both of these closed-source programs
are out of our reach to fix... so we turn to our own.


2. How do I use/install lphdisk?
--------------------------------

Grab the latest source from http://www.procyon.com/~pda/lphdisk/ then:

   tar -xvvvzf lphdisk-0.9.1.tar.gz
   cd lphdisk-0.9.1
   make install

... and you're all set and ready to use lpdisk to prep your partition.

Currently, usage is very simple for lphdisk. First you need to determine 
how much space to allocate. A general rule of thumb that works fine is to
add your physical system memory, your video memory, and 2 megabytes (for
caches and bad block growth) together. For example, my laptop has 256MB of
RAM and 8MB of video RAM. That's 256+8+2, or 266 megabytes. Alternately,
you can run "lphdisk --probeonly" and it will try to determine a good size
for you.

Use a partitioning utility to create a partition of this size. This partition
should be a primary partition. You may need to use GNU parted to
resize other partitions and filesystems on the hard drive to get enough space.
Once you create the partition, set its type to a0 - the IBM "ThinkPad"
Hibernation format. Save the partition table and you're ready to use lphdisk.
NOTE: If the kernel fails to reread the partition table after repartitioning,
you should reboot to ensure this happens. It's probably a good idea to reboot
anyway to make sure the kernel knows the partition table... otherwise, this
could interfere with lphdisk and do Bad Things(tm) to your hard drive.

AS WITH ANY SOFTWARE THAT DIRECTLY MANIPULATES THE HARD DRIVE AND RUNS WITH
ROOT PRIVILEGES, BE WARNED THAT THIS COULD BRING ABOUT UNFORESEEN CONSEQUENCES.

In other words, BACK UP YOUR DATA BEFORE USING THIS!!!

While I am confident that my utility is less likely to destroy data than the
official DOS equivalent, and I personally trust my code enough to use it
without backing up my partitions, I cannot suggest anyone else do the same.
Use this at your own risk.

Now that you're all set, the partition is in place, and you have backed up your
drive (you DID back up your drive, didn't you?), you're ready to evoke ye old
magic incantation:

  lphdisk
    or
  lphdisk /dev/hda

Now reboot so that the Phoenix NoteBIOS can find and verify the new hibernation
partition, and you're ready to use the suspend-to-disk feature.

There are a few more options and functions now available in lphdisk. Type
"lphdisk --help" or read the included man page for more information.


3. Do I need lphdisk to use hibernation with Linux?
---------------------------------------------------

No. If your laptop already has a prepared hibernation partition, either as
shipped from the laptop manufacturer or as generated by the DOS-only PHDISK.EXE
utility, you should be able to suspend-to-disk from any operating system that
can handle APM suspend events.

This utility just makes it easier for Linux users to prepare a valid
hibernation partition. It also makes it safer. Before this utility, one had
to obtain the PHDISK.EXE from Phoenix (or usually on a rescue CD shipped with
the laptop), boot to DOS, and hope that it didn't nuke anything else on the
drive when it ran.


4. What kind of laptops will lphdisk work with?
-----------------------------------------------

Theoretically, any laptop that uses Phoenix NoteBIOS, but I do not have an
extremely wide test base to verify this. All of the models I have tested use
Phoenix NoteBIOS 4.0 Release 6.1, but earlier version may (should?) work.

There is a fairly good size list of laptops that have been tested and work
just fine with hibernation partitions available on lphdisk's home page at:

  http://www.procyon.com/~pda/lphdisk/tested.html


5. About the Artistic License
-----------------------------

This software is released under the Artistic License. Please see the "LICENSE"
file included with this package or online at either of the following URLs:

   http://www.perl.com/language/misc/Artistic.html
   http://www.opensource.org/licenses/artistic-license.html

I chose to release lphdisk under the Artistic License rather than the GPL
because the GPL is too restrictive and is incompatible with other licenses that
could possibly restrict redistribution. (example, the BSD license)

