
                           lphdisk release 0.4
                              July 27, 2000
                   Patrick D. Ashmore <pda@procyon.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 work for sells laptops with Linux, and
having to involve DOS in our laptop build process greatly slowed things down.
Now that we can have the entire build process run from within Linux, the 
process will be much faster and less error prone.

Did I say two reasons? I meant three. The third reason is that I wanted a
hibernation partition prep program that worked. PHDISK.EXE did work, for small
values of work. PHDISK.EXE did little or no checking on the target hard drive,
so it was extremely easy to nuke data because it would overwrite preexisting
partitions. It also has a bad habit of ending the partition on a non cylinder
boundary. It sometimes puts the actual partition slightly offset from where it
specified in the partition table. All of these rolled together plus the fact
that it runs under DOS makes it a terrible piece of software, in my opinion. My
prep utility will run in a much more well behaved manor.

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

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

   tar -xvvvzf lphdisk-0.4.tar.gz
   cd lphdisk-0.4
   make

... and it's ready to use! Currently there are no install options in the
makefile, as the utility has a few more days worth of work before being 
"installable" software (in my opinion, anyway). The next release (which is
just around the corner) will include the ability to install the utility.
RPM and Debian packages will also be released at this time.

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. 

Use a partitioning utility to create a partition of this size. This partition
should be the fourth 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 interfear 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.

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.

Following is a short list of machines that have been tested:

  ARMNote TS290i
  ARMNote TS30W
  ARMNote TS795Plus
  ARMNote TS982
  Dell Inspiron 5000
  Sony VAIO PCG-F340
  Tuxtops Premium 30w
  Tuxtops Standard 982
  Tuxtops Value 795+
  Tuxtops Ultralight 290i

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)

