Table of Contents
=================
  Introduction
  Packaging
  Installing Source RPM Package
  Uninstall
  Device Nodes
  Status Information
  Hot Add Failures
  Notes

Introduction
============
The ham (Hot Add Memory) driver, along with the memhotadd kernel patch and the
hardware specific memory hotplug driver, provides Hot Add Memory support for 
the Linux system. The ham driver acts as a conduit between the underlying 
hardware specific memory hot-plug controller driver and the Kernel Virtual 
Memory (with memhotadd patches). Please install the memhotadd patch before 
installing this driver.

After installation additional information can be found in the files located at:

For Red Hat: /usr/share/doc/ham-<version>/README
For SuSE:    /usr/share/doc/packages/ham/README

Packaging
=========
The driver is released in a source RPM format. The file name for the package
is ham-<version>.src.rpm and is dependent on the following :-

* The system should be booted with the kernel with memhotadd patches.
* The kernel source code (with memhotadd patches) should be present.

Installing Source RPM Package
=============================
This step assumes that you are running a kernel with memhotadd patches and
have set up a kernel tree with memhotadd patches at 
/usr/src/linux-<kernel-version>, where <kernel-version> is the version number
of the booted kernel with memhotadd patches.

1. Install the source RPM package.

        # rpm -ivh ham-<version>.src.rpm

2. Build the binary RPM for the ham driver.

    Red Hat Installation:
    # cd /usr/src/redhat
    # rpmbuild -bb SPECS/ham.spec

    SuSE Installation:
    # cd /usr/src/packages
    # rpm -bb SPECS/ham.spec

4. Install the new RPM package.  This installs the ham driver.

        # rpm -ivh RPMS/i386/ham-<version>.i386.rpm

        If an older version of ham already exists, please use the "update" 
    command as shown below.

        # rpm -uvh RPMS/i386/ham-<version>.i386.rpm

        The ham.o driver will be installed in the following path:

        /lib/modules/<kernel_version>/kernel/misc/ham.o

    Installing the ham binary RPM will install the ham driver and 
    startup/shutdown init scripts. The driver will also be loaded at the 
    end of the installation.

5. You can now reboot your server. Upon reboot the ham driver should be
   loaded. To verify that the ham driver is loaded use the following command.

        # lsmod

    If ham is listed then the ham driver is loaded.

Uninstall
=========
The ham package can be uninstalled by

rpm -e ham

The ham driver will be unloaded and all files installed as part of the ham
package will be removed.

Device Nodes
============
The major device number for the accessing the ham driver through a ham device
is generated automatically. The ham device, /dev/ham, will be created 
by the startup script after loading the ham driver.

Status Information
==================
The ham driver the following external interface to obtain the status of 
hot-added memory regions.

/proc/ham/status

The output is in the following format
<ID>    <START> <SIZE> <FLAGS> <STATUS>

where,

ID       : Index of the memory region
START    : Start address
SIZE     : Size in bytes
FLAGS    : READ/WRITE, READ or WRITE
STATUS   : ENABLED/FAILED

Hot Add Failures
================
Successful integration of the hot-added memory to the system depends on 
available system resources at the time of hotadd. Sometimes, due to 
insufficient system resources, the hot-add operation can fail. In such
case, the /proc/ham/status will show the memory region as "FAILED".

The /opt/compaq/ham/ham_integrate tool can be used to attempt re-integration of all memory 
regions that failed to hot-add. This program is not guaranteed to succeed as 
any memory hot-add operation is dependent on the available system resources.
However, this program can be used multiple times to attempt re-integration.

Notes
=====
* The ham driver should only be loaded using the startup/shutdown
  scripts in /etc/init.d. Loading the ham driver directly (visa insmod) is not 
  recommended.

* The device major number for the ham device is generated automatically
  upon loading of the ham driver. The ham startup script creates appropriate 
  devices files (/dev entries) after loading the ham driver. Users are advised
  not to remove/rename the device files.

* The ham driver is tied to the kernel booted at the time of ham driver 
  installation. If the kernel is changed/recompiled, the ham driver needs 
  to be reinstalled. In that case, the following steps are to be followed :-

  - Boot with the modified kernel (with mem_hotadd patch)
  - Uninstall the ham package (refer Uninstall section above)
  - Recreate and install ham binary RPM package (refer Install section above)
    It is not necessary to install the src RPM package again.

Copyright 2003, Hewlett-Packard company.  All rights reserved.

Product names mentioned herein may be trademarks and/or registered trademarks
of their respective companies.