$Id$
-virt-df is a 'df' tool for printing out the used and available disk
-space in all active and inactive domains. Without this tool you would
-need to log in to each domain individually or set up monitoring.
-
-It is only a proof-of-concept. Please bare in mind the following
-limitations when using this tool:
-
-(1) It does not work over remote connections. Part of the reason why
-I wrote virt-df was to get an idea of how the remote storage API for
-libvirt might look.
-
-(2) It only understands a limited set of partition types. Assuming
-that the files and partitions that we get back from libvirt / Xen
-correspond to block devices in the guests, we can go some way towards
-manually parsing those partitions to find out what they contain. We
-can read the MBR, LVM, superblocks and so on. However that's a lot of
-parsing work, and currently there is no library which understands a
-wide range of partition schemes and filesystem types (not even
-libparted which doesn't support LVM yet). The Linux kernel does
-support that, but there's not really any good way to access that work.
-
-The current implementation uses a hand-coded parser which understands
-some simple formats (MBR, LVM2, ext2/3). In future we should use
-something like libparted.
-
-(3) The statistics you get are delayed. The real state of, for
-example, an ext2 filesystem is only stored in the memory of the
-guest's kernel. The ext2 superblock contains some meta-information
-about blocks used and free, but this superblock is not up to date. In
-fact the guest kernel may not update it even on a 'sync', not until
-the filesystem is unmounted. Some operations do appear to write the
-superblock, for example fsync(2) [that is my reading of the ext2/3
-source code at least].
+For user documentation:
+
+Please see the manual page (virt-df.pod or virt-df.txt in this
+directory).
+
+Developer documentation
+----------------------------------------------------------------------
+
+This program has suddenly become rather large and confusing.
+Hopefully this documentation should go some way towards explaining
+what is going on inside the source.
+
+The main program consists of two modules:
+
+ - virt_df.ml / virt_df.mli (module name: Virt_df)
+
+ This has evolved into a library of miscellaneous functions
+ and values which are included throughout the rest of the
+ program. If you see an unexplained function then it's
+ likely that it is defined in here.
+
+ Start by reading virt_df.mli which contains the full types
+ and plenty of documentation.
+
+ - virt_df_main.ml
+
+ This is the program. It reads the command line arguments,
+ loads the domain descriptions, calls out to the plug-ins
+ to probe for disks / partitions / filesystems / etc., and
+ finally prints the results.
+
+ The file consists of basically one large program that
+ does all of the above in sequence.
+
+Everything else in this directory is a plug-in specialized for probing
+a particular filesystem, partition scheme or type of LVM. The
+plug-ins at time of writing are:
+
+ - virt_df_ext2.ml / virt_df_ext2.mli
+
+ EXT2/3/4 plug-in.
+
+ - virt_df_linux_swap.ml / virt_df_linux_swap.mli
+
+ Linux swap (new style) plug-in.
+
+ - virt_df_mbr.ml / virt_df_mbr.mli
+
+ Master Boot Record (MS-DOS) disk partitioning plug-in.
+
+ - virt_df_lvm2*
+
+ LVM2 parsing, which is by far the most complex plug-in.
+ It consists of:
+
+ - virt_df_lvm2.ml
+ - virt_df_lvm2.mli
+ LVM2 probing, PV detection.
+
+ - virt_df_lvm2_parser.mly
+ - virt_df_lvm2_lexer.mll
+ Scanner/parser for parsing LVM2 metadata definitions.
+
+ - virt_df_lvm2_metadata.ml
+ - virt_df_lvm2_metadata.mli
+ AST for LVM2 metadata definitions.
git.annexia.org / virt-top.git / blobdiff