X-Git-Url: http://git.annexia.org/?a=blobdiff_plain;f=src%2Fguestfs.pod;h=06c3530f20f56503843f9cc06f729e5b5e80d04c;hb=refs%2Ftags%2F1.13.12;hp=a1831c0d0d23e81b5396b2a50cef0d8c8cb4353c;hpb=1bf3941b9ccabef122cc6479004d18ddcb935eef;p=libguestfs.git

diff --git a/src/guestfs.pod b/src/guestfs.pod
index a1831c0..06c3530 100644
--- a/src/guestfs.pod
+++ b/src/guestfs.pod
@@ -1453,8 +1453,8 @@ Returns the current error handler callback.
 =head2 guestfs_set_out_of_memory_handler
 
  typedef void (*guestfs_abort_cb) (void);
- int guestfs_set_out_of_memory_handler (guestfs_h *g,
-                                        guestfs_abort_cb);
+ void guestfs_set_out_of_memory_handler (guestfs_h *g,
+                                         guestfs_abort_cb);
 
 The callback C<cb> will be called if there is an out of memory
 situation.  I<Note this callback must not return>.
@@ -1833,6 +1833,21 @@ If no callback is registered: the messages are sent to stderr.  You
 can override the printing of trace messages to stderr by setting up a
 callback.
 
+=item GUESTFS_EVENT_ENTER
+(payload type: function name)
+
+The callback function is called whenever a libguestfs function
+is entered.
+
+The payload is a string which contains the name of the function
+that we are entering (not including C<guestfs_> prefix).
+
+Note that libguestfs functions can call themselves, so you may
+see many events from a single call.  A few libguestfs functions
+do not generate this event.
+
+If no callback is registered: the event is ignored.
+
 =back
 
 =head3 guestfs_set_event_callback
@@ -2228,6 +2243,99 @@ callback to receive these messages.
 
 =head1 INTERNALS
 
+=head2 APPLIANCE BOOT PROCESS
+
+This process has evolved and continues to evolve.  The description
+here corresponds only to the current version of libguestfs and is
+provided for information only.
+
+In order to follow the stages involved below, enable libguestfs
+debugging (set the environment variable C<LIBGUESTFS_DEBUG=1>).
+
+=over 4
+
+=item Create the appliance
+
+C<febootstrap-supermin-helper> is invoked to create the kernel, a
+small initrd and the appliance.
+
+The appliance is cached in C</var/tmp/.guestfs-E<lt>UIDE<gt>> (or in
+another directory if C<TMPDIR> is set).
+
+For a complete description of how the appliance is created and cached,
+read the L<febootstrap(8)> and L<febootstrap-supermin-helper(8)> man
+pages.
+
+=item Start qemu and boot the kernel
+
+qemu is invoked to boot the kernel.
+
+=item Run the initrd
+
+C<febootstrap-supermin-helper> builds a small initrd.  The initrd is
+not the appliance.  The purpose of the initrd is to load enough kernel
+modules in order that the appliance itself can be mounted and started.
+
+The initrd is a cpio archive called
+C</var/tmp/.guestfs-E<lt>UIDE<gt>/initrd>.
+
+When the initrd has started you will see messages showing that kernel
+modules are being loaded, similar to this:
+
+ febootstrap: ext2 mini initrd starting up
+ febootstrap: mounting /sys
+ febootstrap: internal insmod libcrc32c.ko
+ febootstrap: internal insmod crc32c-intel.ko
+
+=item Find and mount the appliance device
+
+The appliance is a sparse file containing an ext2 filesystem which
+contains a familiar (although reduced in size) Linux operating system.
+It would normally be called C</var/tmp/.guestfs-E<lt>UIDE<gt>/root>.
+
+The regular disks being inspected by libguestfs are the first
+devices exposed by qemu (eg. as C</dev/vda>).
+
+The last disk added to qemu is the appliance itself (eg. C</dev/vdb>
+if there was only one regular disk).
+
+Thus the final job of the initrd is to locate the appliance disk,
+mount it, and switch root into the appliance, and run C</init> from
+the appliance.
+
+If this works successfully you will see messages such as:
+
+ febootstrap: picked /sys/block/vdb/dev as root device
+ febootstrap: creating /dev/root as block special 252:16
+ febootstrap: mounting new root on /root
+ febootstrap: chroot
+ Starting /init script ...
+
+Note that C<Starting /init script ...> indicates that the appliance's
+init script is now running.
+
+=item Initialize the appliance
+
+The appliance itself now initializes itself.  This involves starting
+certain processes like C<udev>, possibly printing some debug
+information, and finally running the daemon (C<guestfsd>).
+
+=item The daemon
+
+Finally the daemon (C<guestfsd>) runs inside the appliance.  If it
+runs you should see:
+
+ verbose daemon enabled
+
+The daemon expects to see a named virtio-serial port exposed by qemu
+and connected on the other end to the library.
+
+The daemon connects to this port (and hence to the library) and sends
+a four byte message C<GUESTFS_LAUNCH_FLAG>, which initiates the
+communication protocol (see below).
+
+=back
+
 =head2 COMMUNICATION PROTOCOL
 
 Don't rely on using this protocol directly.  This section documents