[libvirt PATCH 3/9] docs: html.in: Convert api to rst
Erik Skultety
eskultet at redhat.com
Fri Mar 12 11:43:06 UTC 2021
There were a number of occurrences where we used nested inline markup
(verbatim + refs) which is currently not possible with RST syntax [1].
There is a possible workaround involving substitution definitions like
.. |virConnectPtr| replace:: ``virConnectPtr``
.. _virConnectPtr: /html/libvirt-libvirt-host.html#virConnectPtr
Substitutions cannot be made generic, hence we cannot create a template
for substitution and use a single template everywhere, so we'd end up
with a lot of clutter and convolution. Therefore, we can make an
exception and just link the data type without further style markup.
[1] https://docutils.sourceforge.io/FAQ.html#is-nested-inline-markup-possible
Signed-off-by: Erik Skultety <eskultet at redhat.com>
---
docs/api.html.in | 380 -----------------------------------------------
docs/api.rst | 265 +++++++++++++++++++++++++++++++++
docs/meson.build | 2 +-
3 files changed, 266 insertions(+), 381 deletions(-)
delete mode 100644 docs/api.html.in
create mode 100644 docs/api.rst
diff --git a/docs/api.html.in b/docs/api.html.in
deleted file mode 100644
index 4bff037d48..0000000000
--- a/docs/api.html.in
+++ /dev/null
@@ -1,380 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml">
- <body>
- <h1>The libvirt API concepts</h1>
-
- <p> This page describes the main principles and architecture choices
- behind the definition of the libvirt API:</p>
-
- <ul id="toc"></ul>
-
- <h2><a id="Objects">Objects Exposed</a></h2>
- <p> As defined in the <a href="goals.html">goals section</a>, the libvirt
- API is designed to expose all the resources needed to manage the
- virtualization support of recent operating systems. The first object
- manipulated through the API is the <code>virConnectPtr</code>, which
- represents the connection to a hypervisor. Any application using libvirt
- is likely to start using the
- API by calling one of <a href="html/libvirt-libvirt-host.html#virConnectOpen"
- >the virConnectOpen functions</a>. You will note that those functions take
- a name argument which is actually a <a href="uri.html">connection URI</a>
- to select the right hypervisor to open.
- A URI is needed to allow remote connections and also select between
- different possible hypervisors. For example, on a Linux system it may be
- possible to use both KVM and LinuxContainers on the same node. A NULL
- name will default to a preselected hypervisor, but it's probably not a
- wise thing to do in most cases. See the <a href="uri.html">connection
- URI</a> page for a full descriptions of the values allowed.</p>
- <p> OnDevice the application obtains a
- <a href="/html/libvirt-libvirt-host.html#virConnectPtr">
- <code>virConnectPtr</code>
- </a>
- connection to the hypervisor it can then use it to manage the hypervisor's
- available domains and related virtualization
- resources, such as storage and networking. All those are
- exposed as first class objects and connected to the hypervisor connection
- (and the node or cluster where it is available).</p>
- <p class="image">
- <img alt="first class objects exposed by the API"
- src="libvirt-object-model.png"/>
- </p>
- <p> The figure above shows the five main objects exported by the API:</p>
- <ul>
- <li>
- <a href="html/libvirt-libvirt-host.html#virConnectPtr">
- <code>virConnectPtr</code>
- </a>
- <p>Represents the connection to a hypervisor. Use one of the
- <a href="html/libvirt-libvirt-host.html#virConnectOpen">virConnectOpen</a>
- functions to obtain connection to the hypervisor which is then used
- as a parameter to other connection API's.</p></li>
- <li>
- <a href="html/libvirt-libvirt-domain.html#virDomainPtr">
- <code>virDomainPtr</code>
- </a>
- <p>Represents one domain either active or defined (i.e. existing as
- permanent config file and storage but not currently running on that
- node). The function
- <a href="html/libvirt-libvirt-domain.html#virConnectListAllDomains">
- <code>virConnectListAllDomains</code>
- </a>
- lists all the domains for the hypervisor.</p></li>
- <li>
- <a href="html/libvirt-libvirt-network.html#virNetworkPtr">
- <code>virNetworkPtr</code>
- </a>
- <p>Represents one network either active or defined (i.e. existing
- as permanent config file and storage but not currently activated).
- The function
- <a href="html/libvirt-libvirt-network.html#virConnectListAllNetworks">
- <code>virConnectListAllNetworks</code>
- </a>
- lists all the virtualization networks for the hypervisor.</p></li>
- <li>
- <a href="html/libvirt-libvirt-storage.html#virStorageVolPtr">
- <code>virStorageVolPtr</code>
- </a>
- <p>Represents one storage volume generally used
- as a block device available to one of the domains. The function
- <a href="html/libvirt-libvirt-storage.html#virStorageVolLookupByPath">
- <code>virStorageVolLookupByPath</code>
- </a>
- finds the storage volume object based on its path on the node.</p></li>
- <li>
- <a href="html/libvirt-libvirt-storage.html#virStoragePoolPtr">
- <code>virStoragePoolPtr</code>
- </a>
- <p>Represents a storage pool, which is a logical area
- used to allocate and store storage volumes. The function
- <a href="html/libvirt-libvirt-storage.html#virConnectListAllStoragePools">
- <code>virConnectListAllStoragePools</code>
- </a>
- lists all of the virtualization storage pools on the hypervisor.
- The function
- <a href="html/libvirt-libvirt-storage.html#virStoragePoolLookupByVolume">
- <code>virStoragePoolLookupByVolume</code>
- </a>
- finds the storage pool containing a given storage volume.</p></li>
- </ul>
- <p> Most objects manipulated by the library can also be represented using
- XML descriptions. This is used primarily to create those object, but is
- also helpful to modify or save their description back.</p>
- <p> Domains, networks, and storage pools can be either <code>active</code>
- i.e. either running or available for immediate use, or
- <code>defined</code> in which case they are inactive but there is
- a permanent definition available in the system for them. Based on this
- they can be activated dynamically in order to be used.</p>
- <p> Most objects can also be named in various ways:</p>
- <ul>
- <li><code>name</code>
- <p>A user friendly identifier but whose uniqueness
- cannot be guaranteed between two nodes.</p></li>
- <li><code>ID</code>
- <p>A runtime unique identifier
- provided by the hypervisor for one given activation of the object;
- however, it becomes invalid once the resource is deactivated.</p></li >
- <li><code>UUID</code>
- <p> A 16 byte unique identifier
- as defined in <a href="https://www.ietf.org/rfc/rfc4122.txt">RFC 4122</a>,
- which is guaranteed to be unique for long term usage and across a
- set of nodes.</p></li>
- </ul>
-
- <h2><a id="Functions">Functions and Naming Conventions</a></h2>
- <p> The naming of the functions present in the library is usually
- composed by a prefix describing the object associated to the function
- and a verb describing the action on that object.</p>
- <p> For each first class object you will find APIs
- for the following actions:</p>
- <ul>
- <li><b>Lookup</b> [...LookupBy...]
- <p>Used to perform lookups on objects by some type of identifier,
- such as:</p>
- <ul>
- <li>
- <a href="html/libvirt-libvirt-domain.html#virDomainLookupByID">
- <code>virDomainLookupByID</code>
- </a>
- </li>
- <li>
- <a href="html/libvirt-libvirt-domain.html#virDomainLookupByName">
- <code>virDomainLookupByName</code>
- </a>
- </li>
- <li>
- <a href="html/libvirt-libvirt-domain.html#virDomainLookupByUUID">
- <code>virDomainLookupByUUID</code>
- </a>
- </li>
- <li>
- <a href="html/libvirt-libvirt-domain.html#virDomainLookupByUUIDString">
- <code>virDomainLookupByUUIDString</code>
- </a>
- </li>
- </ul>
- </li>
- <li><b>Enumeration</b> [virConnectList..., virConnectNumOf...]
- <p>Used to enumerate a set of object available to a given
- hypervisor connection such as:</p>
- <ul>
- <li>
- <a href="html/libvirt-libvirt-domain.html#virConnectListDomains">
- <code>virConnectListDomains</code>
- </a>
- </li>
- <li>
- <a href="html/libvirt-libvirt-domain.html#virConnectNumOfDomains">
- <code>virConnectNumOfDomains</code>
- </a>
- </li>
- <li>
- <a href="html/libvirt-libvirt-network.html#virConnectListNetworks">
- <code>virConnectListNetworks</code>
- </a>
- </li>
- <li>
- <a href="html/libvirt-libvirt-storage.html#virConnectListStoragePools">
- <code>virConnectListStoragePools</code>
- </a>
- </li>
- </ul>
- </li>
- <li><b>Description</b> [...GetInfo]
- <p>Generic accessor providing a set of generic information about an
- object, such as: </p>
- <ul>
- <li>
- <a href="html/libvirt-libvirt-host.html#virNodeGetInfo">
- <code>virNodeGetInfo</code>
- </a>
- </li>
- <li>
- <a href="html/libvirt-libvirt-domain.html#virDomainGetInfo">
- <code>virDomainGetInfo</code>
- </a>
- </li>
- <li>
- <a href="html/libvirt-libvirt-storage.html#virStoragePoolGetInfo">
- <code>virStoragePoolGetInfo</code>
- </a>
- </li>
- <li>
- <a href="html/libvirt-libvirt-storage.html#virStorageVolGetInfo">
- <code>virStorageVolGetInfo</code>
- </a>
- </li>
- </ul>
- </li>
- <li><b>Accessors</b> [...Get..., ...Set...]
- <p>Specific accessors used to query or modify data for the given object,
- such as: </p>
- <ul>
- <li>
- <a href="html/libvirt-libvirt-host.html#virConnectGetType">
- <code>virConnectGetType</code>
- </a>
- </li>
- <li>
- <a href="html/libvirt-libvirt-domain.html#virDomainGetMaxMemory">
- <code>virDomainGetMaxMemory</code>
- </a>
- </li>
- <li>
- <a href="html/libvirt-libvirt-domain.html#virDomainSetMemory">
- <code>virDomainSetMemory</code>
- </a>
- </li>
- <li>
- <a href="html/libvirt-libvirt-domain.html#virDomainGetVcpus">
- <code>virDomainGetVcpus</code>
- </a>
- </li>
- <li>
- <a href="html/libvirt-libvirt-storage.html#virStoragePoolSetAutostart">
- <code>virStoragePoolSetAutostart</code>
- </a>
- </li>
- <li>
- <a href="html/libvirt-libvirt-network.html#virNetworkGetBridgeName">
- <code>virNetworkGetBridgeName</code>
- </a>
- </li>
- </ul>
- </li>
- <li><b>Creation</b> [...Create, ...CreateXML]
- <p>Used to create and start objects. The ...CreateXML APIs will create
- the object based on an XML description, while the ...Create APIs will
- create the object based on existing object pointer, such as: </p>
- <ul>
- <li>
- <a href="html/libvirt-libvirt-domain.html#virDomainCreate">
- <code>virDomainCreate</code>
- </a>
- </li>
- <li>
- <a href="html/libvirt-libvirt-domain.html#virDomainCreateXML">
- <code>virDomainCreateXML</code>
- </a>
- </li>
- <li>
- <a href="html/libvirt-libvirt-network.html#virNetworkCreate">
- <code>virNetworkCreate</code>
- </a>
- </li>
- <li>
- <a href="html/libvirt-libvirt-network.html#virNetworkCreateXML">
- <code>virNetworkCreateXML</code>
- </a>
- </li>
- </ul>
- </li>
- <li><b>Destruction</b> [...Destroy]
- <p>Used to shutdown or deactivate and destroy objects, such as: </p>
- <ul>
- <li>
- <a href="html/libvirt-libvirt-domain.html#virDomainDestroy">
- <code>virDomainDestroy</code>
- </a>
- </li>
- <li>
- <a href="html/libvirt-libvirt-network.html#virNetworkDestroy">
- <code>virNetworkDestroy</code>
- </a>
- </li>
- <li>
- <a href="html/libvirt-libvirt-storage.html#virStoragePoolDestroy">
- <code>virStoragePoolDestroy</code>
- </a>
- </li>
- </ul>
- </li>
- </ul>
- <p>Note: functions returning vir*Ptr (like the virDomainLookup functions)
- allocate memory which needs to be freed by the caller by the corresponding
- vir*Free function (e.g. virDomainFree for a virDomainPtr object).
- </p>
- <p> For more in-depth details of the storage related APIs see
- <a href="storage.html">the storage management page</a>.
- </p>
- <h2><a id="Drivers">The libvirt Drivers</a></h2>
- <p>Drivers are the basic building block for libvirt functionality
- to support the capability to handle specific hypervisor driver calls.
- Drivers are discovered and registered during connection processing as
- part of the
- <a href="html/libvirt-libvirt-host.html#virInitialize">
- <code>virInitialize</code>
- </a>
- API. Each driver
- has a registration API which loads up the driver specific function
- references for the libvirt APIs to call. The following is a simplistic
- view of the hypervisor driver mechanism. Consider the stacked list of
- drivers as a series of modules that can be plugged into the architecture
- depending on how libvirt is configured to be built.</p>
- <p class="image">
- <img alt="The libvirt driver architecture"
- src="libvirt-driver-arch.png"/>
- </p>
- <p>The driver architecture is also used to support other virtualization
- components such as storage, storage pools, host device, networking,
- network interfaces, and network filters.</p>
- <p>See the <a href="drivers.html">libvirt drivers</a> page for more
- information on hypervisor and storage specific drivers.</p>
- <p>Not all drivers support every virtualization function possible.
- The <a href="hvsupport.html">libvirt API support matrix</a> lists
- the various functions and support found in each driver by the version
- support was added into libvirt.
- </p>
- <h2><a id="Remote">Daemon and Remote Access</a></h2>
- <p>Access to libvirt drivers is primarily handled by the libvirtd
- daemon through the <a href="remote.html">remote</a> driver via an
- <a href="internals/rpc.html">RPC</a>. Some hypervisors do support
- client-side connections and responses, such as Test, OpenVZ, VMware,
- VirtualBox (vbox), ESX, Hyper-V, Xen, and Virtuozzo.
- The libvirtd daemon service is started on the host at system boot
- time and can also be restarted at any time by a properly privileged
- user, such as root. The libvirtd daemon uses the same libvirt API
- <a href="html/libvirt-libvirt-host.html#virInitialize">
- <code>virInitialize</code>
- </a>
- sequence as applications
- for client-side driver registrations, but then extends the registered
- driver list to encompass all known drivers supported for all driver
- types supported on the host. </p>
- <p>The libvirt client <a href="apps.html">applications</a> use a
- <a href="uri.html">URI</a> to obtain the <code>virConnectPtr</code>.
- The <code>virConnectPtr</code> keeps track of the driver connection
- plus a variety of other connections (network, interface, storage, etc.).
- The <code>virConnectPtr</code> is then used as a parameter to other
- virtualization <a href="#Functions">functions</a>. Depending upon the
- driver being used, calls will be routed through the remote driver to
- the libvirtd daemon. The daemon will reference the connection specific
- driver in order to retrieve the requested information and then pass
- back status and/or data through the connection back to the application.
- The application can then decide what to do with that data, such as
- display, write log data, etc. <a href="migration.html">Migration</a>
- is an example of many facets of the architecture in use.</p>
-
- <p class="image">
- <img alt="The libvirt daemon and remote architecture"
- src="libvirt-daemon-arch.png"/>
- </p>
- <p>
- The key takeaway from the above diagram is that there is a remote driver
- which handles transactions for a majority of the drivers. The libvirtd
- daemon running on the host will receive transaction requests from the
- remote driver and will then query the hypervisor driver as specified in
- the <code>virConnectPtr</code> in order to fetch the data. The data will
- then be returned through the remote driver to the client application
- for processing.
- </p>
- <p>If you are interested in contributing to libvirt, read the
- <a href="https://wiki.libvirt.org/page/FAQ">FAQ</a> and
- <a href="hacking.html">hacking</a> guidelines to gain an understanding
- of basic rules and guidelines. In order to add new API functionality
- follow the instructions regarding
- <a href="api_extension.html">implementing a new API in libvirt</a>.
- </p>
-
- </body>
-</html>
diff --git a/docs/api.rst b/docs/api.rst
new file mode 100644
index 0000000000..a8f527e197
--- /dev/null
+++ b/docs/api.rst
@@ -0,0 +1,265 @@
+========================
+The libvirt API concepts
+========================
+
+This page describes the main principles and architecture choices behind
+the definition of the libvirt API:
+
+.. contents::
+
+Objects Exposed
+---------------
+
+As defined in the `goals section <goals.html>`__, the libvirt API is
+designed to expose all the resources needed to manage the virtualization
+support of recent operating systems. The first object manipulated
+through the API is the ``virConnectPtr``, which represents the
+connection to a hypervisor. Any application using libvirt is likely to
+start using the API by calling one of `the virConnectOpen
+functions <html/libvirt-libvirt-host.html#virConnectOpen>`__. You will
+note that those functions take a name argument which is actually a
+`connection URI <uri.html>`__ to select the right hypervisor to open. A
+URI is needed to allow remote connections and also select between
+different possible hypervisors. For example, on a Linux system it may be
+possible to use both KVM and LinuxContainers on the same node. A NULL
+name will default to a preselected hypervisor, but it's probably not a
+wise thing to do in most cases. See the `connection URI <uri.html>`__
+page for a full descriptions of the values allowed.
+
+OnDevice the application obtains a
+`virConnectPtr </html/libvirt-libvirt-host.html#virConnectPtr>`__
+connection to the hypervisor it can then use it to manage the
+hypervisor's available domains and related virtualization resources,
+such as storage and networking. All those are exposed as first class
+objects and connected to the hypervisor connection (and the node or
+cluster where it is available).
+
+|first class objects exposed by the API|
+
+The figure above shows the five main objects exported by the API:
+
+- `virConnectPtr <html/libvirt-libvirt-host.html#virConnectPtr>`__
+
+ Represents the connection to a hypervisor. Use one of the
+ `virConnectOpen <html/libvirt-libvirt-host.html#virConnectOpen>`__
+ functions to obtain connection to the hypervisor which is then used
+ as a parameter to other connection API's.
+
+- `virDomainPtr <html/libvirt-libvirt-domain.html#virDomainPtr>`__
+
+ Represents one domain either active or defined (i.e. existing as
+ permanent config file and storage but not currently running on that
+ node). The function
+ `virConnectListAllDomains <html/libvirt-libvirt-domain.html#virConnectListAllDomains>`__
+ lists all the domains for the hypervisor.
+
+- `virNetworkPtr <html/libvirt-libvirt-network.html#virNetworkPtr>`__
+
+ Represents one network either active or defined (i.e. existing as
+ permanent config file and storage but not currently activated). The
+ function
+ `virConnectListAllNetworks <html/libvirt-libvirt-network.html#virConnectListAllNetworks>`__
+ lists all the virtualization networks for the hypervisor.
+
+- `virStorageVolPtr <html/libvirt-libvirt-storage.html#virStorageVolPtr>`__
+
+ Represents one storage volume generally used as a block device
+ available to one of the domains. The function
+ `virStorageVolLookupByPath <html/libvirt-libvirt-storage.html#virStorageVolLookupByPath>`__
+ finds the storage volume object based on its path on the node.
+
+- `virStoragePoolPtr <html/libvirt-libvirt-storage.html#virStoragePoolPtr>`__
+
+ Represents a storage pool, which is a logical area used to allocate
+ and store storage volumes. The function
+ `virConnectListAllStoragePools <html/libvirt-libvirt-storage.html#virConnectListAllStoragePools>`__
+ lists all of the virtualization storage pools on the hypervisor. The
+ function
+ `virStoragePoolLookupByVolume <html/libvirt-libvirt-storage.html#virStoragePoolLookupByVolume>`__
+ finds the storage pool containing a given storage volume.
+
+Most objects manipulated by the library can also be represented using
+XML descriptions. This is used primarily to create those object, but is
+also helpful to modify or save their description back.
+
+Domains, networks, and storage pools can be either ``active`` i.e.
+either running or available for immediate use, or ``defined`` in which
+case they are inactive but there is a permanent definition available in
+the system for them. Based on this they can be activated dynamically in
+order to be used.
+
+Most objects can also be named in various ways:
+
+- ``name``
+
+ A user friendly identifier but whose uniqueness cannot be guaranteed
+ between two nodes.
+
+- ``ID``
+
+ A runtime unique identifier provided by the hypervisor for one given
+ activation of the object; however, it becomes invalid once the
+ resource is deactivated.
+
+- ``UUID``
+
+ A 16 byte unique identifier as defined in `RFC
+ 4122 <https://www.ietf.org/rfc/rfc4122.txt>`__, which is guaranteed
+ to be unique for long term usage and across a set of nodes.
+
+Functions and Naming Conventions
+--------------------------------
+
+The naming of the functions present in the library is usually composed
+by a prefix describing the object associated to the function and a verb
+describing the action on that object.
+
+For each first class object you will find APIs for the following
+actions:
+
+- **Lookup** [...LookupBy...]
+
+ Used to perform lookups on objects by some type of identifier, such
+ as:
+
+ - `virDomainLookupByID <html/libvirt-libvirt-domain.html#virDomainLookupByID>`__
+ - `virDomainLookupByName <html/libvirt-libvirt-domain.html#virDomainLookupByName>`__
+ - `virDomainLookupByUUID <html/libvirt-libvirt-domain.html#virDomainLookupByUUID>`__
+ - `virDomainLookupByUUIDString <html/libvirt-libvirt-domain.html#virDomainLookupByUUIDString>`__
+
+- **Enumeration** [virConnectList..., virConnectNumOf...]
+
+ Used to enumerate a set of object available to a given hypervisor
+ connection such as:
+
+ - `virConnectListDomains <html/libvirt-libvirt-domain.html#virConnectListDomains>`__
+ - `virConnectNumOfDomains <html/libvirt-libvirt-domain.html#virConnectNumOfDomains>`__
+ - `virConnectListNetworks <html/libvirt-libvirt-network.html#virConnectListNetworks>`__
+ - `virConnectListStoragePools <html/libvirt-libvirt-storage.html#virConnectListStoragePools>`__
+
+- **Description** [...GetInfo]
+
+ Generic accessor providing a set of generic information about an
+ object, such as:
+
+ - `virNodeGetInfo <html/libvirt-libvirt-host.html#virNodeGetInfo>`__
+ - `virDomainGetInfo <html/libvirt-libvirt-domain.html#virDomainGetInfo>`__
+ - `virStoragePoolGetInfo <html/libvirt-libvirt-storage.html#virStoragePoolGetInfo>`__
+ - `virStorageVolGetInfo <html/libvirt-libvirt-storage.html#virStorageVolGetInfo>`__
+
+- **Accessors** [...Get..., ...Set...]
+
+ Specific accessors used to query or modify data for the given object,
+ such as:
+
+ - `virConnectGetType <html/libvirt-libvirt-host.html#virConnectGetType>`__
+ - `virDomainGetMaxMemory <html/libvirt-libvirt-domain.html#virDomainGetMaxMemory>`__
+ - `virDomainSetMemory <html/libvirt-libvirt-domain.html#virDomainSetMemory>`__
+ - `virDomainGetVcpus <html/libvirt-libvirt-domain.html#virDomainGetVcpus>`__
+ - `virStoragePoolSetAutostart <html/libvirt-libvirt-storage.html#virStoragePoolSetAutostart>`__
+ - `virNetworkGetBridgeName <html/libvirt-libvirt-network.html#virNetworkGetBridgeName>`__
+
+- **Creation** [...Create, ...CreateXML]
+
+ Used to create and start objects. The ...CreateXML APIs will create
+ the object based on an XML description, while the ...Create APIs will
+ create the object based on existing object pointer, such as:
+
+ - `virDomainCreate <html/libvirt-libvirt-domain.html#virDomainCreate>`__
+ - `virDomainCreateXML <html/libvirt-libvirt-domain.html#virDomainCreateXML>`__
+ - `virNetworkCreate <html/libvirt-libvirt-network.html#virNetworkCreate>`__
+ - `virNetworkCreateXML <html/libvirt-libvirt-network.html#virNetworkCreateXML>`__
+
+- **Destruction** [...Destroy]
+
+ Used to shutdown or deactivate and destroy objects, such as:
+
+ - `virDomainDestroy <html/libvirt-libvirt-domain.html#virDomainDestroy>`__
+ - `virNetworkDestroy <html/libvirt-libvirt-network.html#virNetworkDestroy>`__
+ - `virStoragePoolDestroy <html/libvirt-libvirt-storage.html#virStoragePoolDestroy>`__
+
+Note: functions returning vir*Ptr (like the virDomainLookup functions)
+allocate memory which needs to be freed by the caller by the
+corresponding vir*Free function (e.g. virDomainFree for a virDomainPtr
+object).
+
+For more in-depth details of the storage related APIs see `the storage
+management page <storage.html>`__.
+
+The libvirt Drivers
+-------------------
+
+Drivers are the basic building block for libvirt functionality to
+support the capability to handle specific hypervisor driver calls.
+Drivers are discovered and registered during connection processing as
+part of the
+`virInitialize <html/libvirt-libvirt-host.html#virInitialize>`__
+API. Each driver has a registration API which loads up the driver
+specific function references for the libvirt APIs to call. The following
+is a simplistic view of the hypervisor driver mechanism. Consider the
+stacked list of drivers as a series of modules that can be plugged into
+the architecture depending on how libvirt is configured to be built.
+
+|The libvirt driver architecture|
+
+The driver architecture is also used to support other virtualization
+components such as storage, storage pools, host device, networking,
+network interfaces, and network filters.
+
+See the `libvirt drivers <drivers.html>`__ page for more information on
+hypervisor and storage specific drivers.
+
+Not all drivers support every virtualization function possible. The
+`libvirt API support matrix <hvsupport.html>`__ lists the various
+functions and support found in each driver by the version support was
+added into libvirt.
+
+Daemon and Remote Access
+------------------------
+
+Access to libvirt drivers is primarily handled by the libvirtd daemon
+through the `remote <remote.html>`__ driver via an
+`RPC <internals/rpc.html>`__. Some hypervisors do support client-side
+connections and responses, such as Test, OpenVZ, VMware, VirtualBox
+(vbox), ESX, Hyper-V, Xen, and Virtuozzo. The libvirtd daemon service is
+started on the host at system boot time and can also be restarted at any
+time by a properly privileged user, such as root. The libvirtd daemon
+uses the same libvirt API
+`virInitialize <html/libvirt-libvirt-host.html#virInitialize>`__
+sequence as applications for client-side driver registrations, but then
+extends the registered driver list to encompass all known drivers
+supported for all driver types supported on the host.
+
+The libvirt client `applications <apps.html>`__ use a `URI <uri.html>`__
+to obtain the ``virConnectPtr``. The ``virConnectPtr`` keeps track of
+the driver connection plus a variety of other connections (network,
+interface, storage, etc.). The ``virConnectPtr`` is then used as a
+parameter to other virtualization `functions <#Functions>`__. Depending
+upon the driver being used, calls will be routed through the remote
+driver to the libvirtd daemon. The daemon will reference the connection
+specific driver in order to retrieve the requested information and then
+pass back status and/or data through the connection back to the
+application. The application can then decide what to do with that data,
+such as display, write log data, etc. `Migration <migration.html>`__ is
+an example of many facets of the architecture in use.
+
+|The libvirt daemon and remote architecture|
+
+The key takeaway from the above diagram is that there is a remote driver
+which handles transactions for a majority of the drivers. The libvirtd
+daemon running on the host will receive transaction requests from the
+remote driver and will then query the hypervisor driver as specified in
+the ``virConnectPtr`` in order to fetch the data. The data will then be
+returned through the remote driver to the client application for
+processing.
+
+If you are interested in contributing to libvirt, read the
+`FAQ <https://wiki.libvirt.org/page/FAQ>`__ and
+`hacking <hacking.html>`__ guidelines to gain an understanding of basic
+rules and guidelines. In order to add new API functionality follow the
+instructions regarding `implementing a new API in
+libvirt <api_extension.html>`__.
+
+.. |first class objects exposed by the API| image:: libvirt-object-model.png
+.. |The libvirt driver architecture| image:: libvirt-driver-arch.png
+.. |The libvirt daemon and remote architecture| image:: libvirt-daemon-arch.png
diff --git a/docs/meson.build b/docs/meson.build
index b031bd6717..942cce6fdc 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -32,7 +32,6 @@ docs_assets = [
docs_html_in_files = [
'404',
- 'api',
'apps',
'architecture',
'auditlog',
@@ -107,6 +106,7 @@ docs_rst_files = [
'aclpolkit',
'advanced-tests',
'api_extension',
+ 'api',
'best-practices',
'ci',
'coding-style',
--
2.29.2
More information about the libvir-list
mailing list