From 8504318756597061bc37de20147367fc5615d6ed Mon Sep 17 00:00:00 2001 From: Richard Jones Date: Wed, 25 Nov 2009 21:41:51 +0000 Subject: [PATCH] guestfs: Update architecture section of documentation. --- guestfs.pod | 79 +++++++++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 53 insertions(+), 26 deletions(-) diff --git a/guestfs.pod b/guestfs.pod index fb16f57..eb043f0 100644 --- a/guestfs.pod +++ b/guestfs.pod @@ -738,32 +738,59 @@ package versioning: Requires: libguestfs >= 1.0.80 -=head1 STATE MACHINE AND LOW-LEVEL EVENT API - -Internally, libguestfs is implemented by running a virtual machine -using L. QEmu runs as a child process of the main program, -and most of this discussion won't make sense unless you understand -that the complexity is dealing with the (asynchronous) actions of the -child process. - - child process - ___________________ _________________________ - / \ / \ - | main program | | qemu +-----------------+| - | | | | Linux kernel || - +-------------------+ | +-----------------+| - | libguestfs <-------------->| guestfsd || - | | | +-----------------+| - \___________________/ \_________________________/ - -The diagram above shows libguestfs communicating with the guestfsd -daemon running inside the qemu child process. There are several -points of failure here: qemu can fail to start, the virtual machine -inside qemu can fail to boot, guestfsd can fail to start or not -establish communication, any component can start successfully but fail -asynchronously later, and so on. - -=head2 STATE MACHINE +=begin html + + + + +=end html + +=head1 ARCHITECTURE + +Internally, libguestfs is implemented by running an appliance (a +special type of small virtual machine) using L. Qemu runs as +a child process of the main program. + + ___________________ + / \ + | main program | + | | + | | child process / appliance + | | __________________________ + | | / qemu \ + +-------------------+ RPC | +-----------------+ | + | libguestfs <--------------------> guestfsd | | + | | | +-----------------+ | + \___________________/ | | Linux kernel | | + | +--^--------------+ | + \_________|________________/ + | + _______v______ + / \ + | Device or | + | disk image | + \______________/ + +The library, linked to the main program, creates the child process and +hence the appliance in the L function. + +Inside the appliance is a Linux kernel and a complete stack of +userspace tools (such as LVM and ext2 programs) and a small +controlling daemon called C. The library talks to +C using remote procedure calls (RPC). There is a mostly +one-to-one correspondence between libguestfs API calls and RPC calls +to the daemon. Lastly the disk image(s) are attached to the qemu +process which translates device access by the appliance's Linux kernel +into accesses to the image. + +A common misunderstanding is that the appliance "is" the virtual +machine. Although the disk image you are attached to might also be +used by some virtual machine, libguestfs doesn't know or care about +this. (But you will care if both libguestfs's qemu process and your +virtual machine are trying to update the disk image at the same time, +since these usually results in massive disk corruption). + +=head1 STATE MACHINE libguestfs uses a state machine to model the child process: -- 1.8.3.1