Implementing a new API in Libvirt

This document walks you through the process of implementing a new API in libvirt. It uses as an example the addition of the node device create and destroy APIs.

Before you begin coding, it is critical that you propose your changes on the libvirt mailing list and get feedback on your ideas to make sure what you're proposing fits with the general direction of the project. Even before doing a proof of concept implementation, send an email giving an overview of the functionality you think should be added to libvirt. Someone may already be working on the feature you want. Also, recognize that everything you write is likely to undergo significant rework as you discuss it with the other developers, so don't wait too long before getting feedback.

Adding a new API to libvirt is not difficult, but there are quite a few steps. This document assumes that you are familiar with C programming and have checked out the libvirt code from the source code repository and successfully built the existing tree. Instructions on how to check out and build the code can be found at:

http://libvirt.org/downloads.html

Once you have a working development environment, the steps to create a new API are:

  1. define the public API
  2. define the internal driver API
  3. implement the public API
  4. define the wire protocol format
  5. implement the RPC client
  6. implement the server side dispatcher
  7. implement the driver methods
  8. add virsh support

It is, of course, possible to implement the pieces in any order, but if the development tasks are completed in the order listed, the code will compile after each step. Given the number of changes required, verification after each step is highly recommended.

Submit new code in the form shown in the example code: one patch per step. That's not to say submit patches before you have working functionality--get the whole thing working and make sure you're happy with it. Then use git or some other version control system that lets you rewrite your commit history and break patches into pieces so you don't drop a big blob of code on the mailing list at one go. For example, I didn't follow my own advice when I originally submitted the example code to the libvirt list but rather submitted it in several large chunks. I've used git's ability to rewrite my commit history to break the code apart into the example patches shown.

Don't mix anything else into the patches you submit. The patches should be the minimal changes required to implement the functionality you're adding. If you notice a bug in unrelated code (i.e., code you don't have to touch to implement your API change) during development, create a patch that just addresses that bug and submit it separately.

With that said, let's begin.

Defining the public API

The first task is to define the public API and add it to:

include/libvirt/libvirt.h.in

This task is in many ways the most important to get right, since once the API has been committed to the repository, it's libvirt's policy never to change it. Mistakes in the implementation are bugs that you can fix. Make a mistake in the API definition and you're stuck with it, so think carefully about the interface and don't be afraid to rework it as you go through the process of implementing it.

Once you have defined the API, you have to add the symbol names to:

src/libvirt_public.syms

See 0001-Step-1-of-8-Define-the-public-API.patch for example code.

Defining the internal API

Each public API call is associated with a driver, such as a host virtualization driver, a network virtualization driver, a storage virtualization driver, a state driver, or a device monitor. Adding the internal API is ordinarily a matter of adding a new member to the struct representing one of these drivers.

Of course, it's possible that the new API will involve the creation of an entire new driver type, in which case the changes will include the creation of a new struct type to represent the new driver type.

The driver structs are defined in:

src/driver.h

To define the internal API, first typedef the driver function prototype and then add a new field for it to the relevant driver struct.

See 0002-Step-2-of-8-Define-the-internal-driver-API.patch

Implementing the public API

Implementing the public API is largely a formality in which we wire up public API to the internal driver API. The public API implementation takes care of some basic validity checks before passing control to the driver implementation. In RFC 2119 vocabulary, this function:

  1. SHOULD log a message with VIR_DEBUG() indicating that it is being called and its parameters;
  2. MUST call virResetLastError();
  3. SHOULD confirm that the connection is valid with VIR_IS_CONNECT(conn);
  4. SECURITY: If the API requires a connection with write privileges, MUST confirm that the connection flags do not indicate that the connection is read-only;
  5. SHOULD do basic validation of the parameters that are being passed in;
  6. MUST confirm that the driver for this connection exists and that it implements this function;
  7. MUST call the internal API;
  8. SHOULD log a message with VIR_DEBUG() indicating that it is returning, its return value, and status.
  9. MUST return status to the caller.

The public API calls are implemented in:

src/libvirt.c

See 0003-Step-3-of-8-Implement-the-public-API.patch

Defining the wire protocol format

Defining the wire protocol is essentially a straightforward exercise which is probably most easily understood by referring to the existing remote protocol wire format definitions and the example patch. It involves making two additions to:

src/remote/remote_protocol.x

First, create two new structs for each new function that you're adding to the API. One struct describes the parameters to be passed to the remote function, and a second struct describes the value returned by the remote function. The one exception to this rule is that functions that return only integer status do not require a struct for returned data.

Second, add values to the remote_procedure enum for each new function added to the API.

See 0004-Step-4-of-8-Define-the-wire-protocol-format.patch

Once these changes are in place, it's necessary to run 'make rpcgen' in the src directory to create the .c and .h files required by the remote protocol code. This must be done on a Linux host using the GLibC rpcgen program. Other rpcgen versions may generate code which results in bogus compile time warnings

Implement the RPC client

Implementing the RPC client is also relatively mechanical, so refer to the exising code and example patch for guidance. The RPC client uses the rpcgen generated .h files. The remote method calls go in:

src/remote/remote_internal.c

Each remote method invocation does the following:

  1. locks the remote driver;
  2. sets up the method arguments;
  3. invokes the remote function;
  4. checks the return value, if necessary;
  5. extracts any returned data;
  6. frees any returned data;
  7. unlocks the remote driver.

Once you have created the remote method calls, you have to add fields for them to the driver structs for the appropriate remote driver.

See 0005-Step-5-of-8-Implement-the-RPC-client.patch

Implement the server side dispatcher

Implementing the server side of the remote function calls is simply a matter of deserializing the parameters passed in from the remote caller and passing them to the corresponding internal API function. The server side dispatchers are implemented in:

daemon/remote.c

Again, this step uses the .h files generated by make rpcgen.

See 0006-Step-6-of-8-Implement-the-server-side-dispatcher.patch

Implement the driver methods

So, after all that, we get to the fun part. All functionality in libvirt is implemented inside a driver. Thus, here is where you implement whatever functionality you're adding to libvirt. You'll either need to add additional files to the src directory or extend files that are already there, depending on what functionality you're adding.

In the example code, the extension is only an additional two function calls in the node device API, so most of the new code is additions to existing files. The only new files are there for multi-platform implementation convenience, as some of the new code is Linux specific.

The example code is probably uninteresting unless you're concerned with libvirt storage, but I've included it here to show how new files are added to the build environment.

See 0007-Step-7-of-8-Implement-the-driver-methods.patch

Implement virsh commands

Once you have the new functionality in place, the easiest way to test it and also to provide it to end users is to implement support for it in virsh.

A virsh command is composed of a few pieces of code. You need to define an array of vshCmdInfo structs for each new command that contain the help text and the command description text. You also need an array of vshCmdOptDef structs to describe the command options. Once you have those pieces of data in place you can write the function implementing the virsh command. Finally, you need to add the new command to the commands[] array.

See 0008-Step-8-of-8-Add-virsh-support.patch

Once you have working functionality, run make check and make syntax-check before generating patches.