README for the disk allocation viewer for linux (davl)

This file contains the following sections:

I.   Introduction
II.  Installation
III. How to use
IV.  How to build RPM packages
V.   License


I. Introduction
===============

This program checks and displays the fragmentation of a ext2 or a ext3
filesystem. It works whether filesystem is mounted or unmounted, and
available for a directory or a file.

Davl requires bellow.
  * kernel source code (optional)
  * memory upper 64MByte
  * GTK+1.2 or GTK+2.0
  * to compile davl, you must have on your system the file header
    /usr/include/ext2fs/ext2_fs.h. Depend on what your linux distro is,
    you are required to have the below package installed:
         - On Redhat or Fedora Core, you need e2fsprogs-devel package
         - On Debian based system (like Debian, Ubutun, Xandros,...),
           you need e2fslibs-dev package
         - On Mandrake/Mandriva, you need libext2fs2-devel package


Davl is checked on the following systems.
  * Fedora Core 2 (Upstream Kernel 2.6.9)
  * Fedora Core 3 (Upstream Kernel 2.6.9)
  * Miracle Linux v3.0 (kernel 2.4.21 that comes with distribution)
  (Some users have reported that Davl can work on the other Linux distributions.
   You can check it on the mailing-list log.)


II. Installation
================

In case of checking a mounted filesystem, if the file on it was modified,
Davl couldn't read this until disk I/O was finished.
If you want to check the mounted filesystem and solve this problem,
you need to build and install the "davl_liveinfo" kernel module.
(The davl_liveinfo kernel module is in the davl-drv_xxx.rpm package.)

In order to build the davl_liveinfo kernel module, knowledge of the kernel
configuration is necessary.


A. Install from rpm package (Fedora Core 2 only)
------------------------------------------------

1. Download davl-XXX-Y.i386.rpm and davl-drv_`uname -r`-XXX-Y.i386.rpm from
   the project page. (XXX,Y is version number of davl rpm package)

2. Do the following command.

   $ su
   (input super-user password here)
   # rpm -Uvh davl-XXX-Y.i386.rpm
   # rpm -Uvh davl-drv_`uname -r`-XXX-Y.i386.rpm


B. Install from source code
---------------------------

1. Preparing kernel source code.
   (optional for preparing the davl_liveinfo build --- case of Fedora Core 2)

  a. Change to super-user

     $ su
     (input super-user password here)

  b. Download and install the kernel source package.

     # rpm -i kernel-2.6.5-1.358.src.rpm

  c. Extract the kernel source

     # rpmbuild -bp --target i686 /usr/src/redhat/SPECS/kernel-2.6.spec

  d. Move to the kernel source directory

     # cd /usr/src/redhat/BUILD/kernel-2.6.5/linux-2.6.5

  e. Edit Makefile, and modify "EXTRAVERSION" line

     # vi Makefile
       ("EXTRAVERSION = -1.358"
        '-1.358' is part of the "uname -r" command result)

  f. Prepare the kernel source for module build
     # make prepare-all

  g. Change to normal-user

     # exit

2. Download davl-XXX.tar.bz2 from the project page.
   (XXX is version number of davl)

3. Extract archive file.

  $ cd $(WHERE_YOUR_WORK_DIRECTORY)
  $ tar jxvf davl-XXX.tar.bz2
  $ cd davl

4. Modify the macro values in the "path_file" according to your system.

       macro     meaning
       --------  ---------------------------------
     * KERN_DIR  kernel source directory
     * BIN_DIR   executable file install directory
     * DRV_DIR   kernel module install directory
     * MAN_DIR   man page install directory
     * GTK_VER   GTK version (use "GTK1" or "GTK2")

5. Build executable file.

  $ make

  or If you want to build the kernel module too, do next

  $ make WITH_DRV=1

6. Install executable file.

  $ su
  (input super-user password here)
  # make install

  or If you want to install the kernel module too, do next

  # make WITH_DRV=1 install


III. How to use
===============

1. If you installed the kernel module, load the davl_liveinfo module before
   executing cdavl or gdavl.

  # modprobe davl_liveinfo

2. Use cdavl or gdavl. For displaying the usage, use -h option.


Use case examples
-----------------

1. Check the partition list. (output text data to stdout)

  # cdavl

2. Check the fragmentation of /dev/hda1. (output text data to stdout)

  # cdavl /dev/hda1

3. Check and view the fragmentation of /dev/hda1.

  # gdavl /dev/hda1
  (GUI window open)

4. Check and view the fragmentation of lost+found directory on /dev/hda1.

  # gdavl /dev/hda1 /lost+found
  (GUI window open)

5. Check the fragmentation of /dev/hda1 and save for checking later by gdavl.

  # cdavl -Tv /dev/hda1 > filename_which_you_like

6. Read the cdavl output file, and display the fragmentation by GUI window.

  # gdavl filename_which_you_saved

7. Check the difference between two cdavl output files.

  # gdavl -d cdavl-out-1 cdavl-out-2

8. Display the animation of three cdavl output files (update each 5 seconds).

  # gdavl -a 5 cdavl-out-1 cdavl-out-2 cdavl-out-3


IV. How to build RPM packages
=============================

1. Build RPM packages for your system

  $ cd $(WHERE_DAVL_EXTRACTED)/rpm
  $ make

2. Build RPM packages for different version of your kernel

  $ cd $(WHERE_DAVL_EXTRACTED)/rpm
  $ make UNAME=X.Y.Z-EXTRA KERN_DIR=$(WHERE_YOUR_KERNEL_SOURCE)

  for example, in case of build rpm packages for the 2.6.5-1.358 kernel,
  you do the following command.

  $ make UNAME=2.6.5-1.358 KERN_DIR=/usr/src/linux-2.6.5-1.358

  !!! CAUTION !!!
  Make sure your kernel source was ready for kernel module compilation.
  For further information, see section II-B-1 "Preparing kernel source code".


V. License
==========

COPYRIGHT (C) HITACHI,LTD. 2004-2007

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.



===
Yumiko Sugita <yumiko.sugita.yf@hitachi.com> and
Satoshi Fujiwara <sa-fuji@sdl.hitachi.co.jp>
