Daniel P. Berrange wrote:

On Wed, May 27, 2009 at 01:08:04PM -0400, David Allan wrote:

...

create mode 100644 docs/api_extension/API_implementation_guide.txt

Nice idea - how'd you actually like to turn this into HTML and wire it into our website ? I think it'd be nice to create a new 'libvirt internals' section in the website for things like your doc, another about adding new XML features, and another about writing new hypervisor drivers, and of course a expanded & HTML-ified version of our 'HACKING.txt'file. You just need to drop a .html.in file into the docs/ directory, and then add a entry to sitemap.html.in to make it appear in the navigation.

Regards, Daniel

Ok, Here's a patch with an HTML version of the doc and the addition to sitemap.html.in I wasn't at all sure where the right place for it in the sitemap is, but I took a swag at it and the HTML version of the doc is much easier to read in any case. I've also added a paragraph on making sure to propose changes to the list before starting coding, per DV's suggestion. Dave

From be8c9e3d1dc89ade9680fa61e4392cc9b523f12b Mon Sep 17 00:00:00 2001 From: David Allan <dallan@redhat.com> Date: Wed, 27 May 2009 12:50:57 -0400 Subject: [PATCH 1/1] Document how to extend the libvirt API

--- .../0001-Step-1-of-8-Define-the-public-API.patch | 45 + ...tep-2-of-8-Define-the-internal-driver-API.patch | 37 + ...0003-Step-3-of-8-Implement-the-public-API.patch | 120 ++ ...ep-4-of-8-Define-the-wire-protocol-format.patch | 48 + ...0005-Step-5-of-8-Implement-the-RPC-client.patch | 85 ++ ...of-8-Implement-the-server-side-dispatcher.patch | 71 ++ ...-Step-7-of-8-Implement-the-driver-methods.patch | 1172 ++++++++++++++++++++ .../0008-Step-8-of-8-Add-virsh-support.patch | 133 +++ docs/api_extension/api_extension.html | 264 +++++ docs/sitemap.html.in | 4 + 10 files changed, 1979 insertions(+), 0 deletions(-) create mode 100644 docs/api_extension/0001-Step-1-of-8-Define-the-public-API.patch create mode 100644 docs/api_extension/0002-Step-2-of-8-Define-the-internal-driver-API.patch create mode 100644 docs/api_extension/0003-Step-3-of-8-Implement-the-public-API.patch create mode 100644 docs/api_extension/0004-Step-4-of-8-Define-the-wire-protocol-format.patch create mode 100644 docs/api_extension/0005-Step-5-of-8-Implement-the-RPC-client.patch create mode 100644 docs/api_extension/0006-Step-6-of-8-Implement-the-server-side-dispatcher.patch create mode 100644 docs/api_extension/0007-Step-7-of-8-Implement-the-driver-methods.patch create mode 100644 docs/api_extension/0008-Step-8-of-8-Add-virsh-support.patch create mode 100644 docs/api_extension/api_extension.html diff --git a/docs/api_extension/0001-Step-1-of-8-Define-the-public-API.patch b/docs/api_extension/0001-Step-1-of-8-Define-the-public-API.patch new file mode 100644 index 0000000..6d0cd68 --- /dev/null +++ b/docs/api_extension/0001-Step-1-of-8-Define-the-public-API.patch @@ -0,0 +1,45 @@ +From 2ae8fd62a1e5e085b7902da9bc207b806d84fd91 Mon Sep 17 00:00:00 2001 +From: David Allan <dallan@redhat.com> +Date: Tue, 19 May 2009 16:16:11 -0400 +Subject: [PATCH] Step 1 of 8 Define the public API + +--- + include/libvirt/libvirt.h.in | 6 ++++++ + src/libvirt_public.syms | 6 ++++++ + 2 files changed, 12 insertions(+), 0 deletions(-) + +diff --git a/include/libvirt/libvirt.h.in b/include/libvirt/libvirt.h.in +index a028b21..2f7076f 100644 +--- a/include/libvirt/libvirt.h.in ++++ b/include/libvirt/libvirt.h.in +@@ -1124,6 +1124,12 @@ int virNodeDeviceDettach (virNodeDevicePtr dev); + int virNodeDeviceReAttach (virNodeDevicePtr dev); + int virNodeDeviceReset (virNodeDevicePtr dev); + ++virNodeDevicePtr virNodeDeviceCreateXML (virConnectPtr conn, ++ const char *xmlDesc, ++ unsigned int flags); ++ ++int virNodeDeviceDestroy (virNodeDevicePtr dev); ++ + /* + * Domain Event Notification + */ +diff --git a/src/libvirt_public.syms b/src/libvirt_public.syms +index f7ebbc3..b8f9128 100644 +--- a/src/libvirt_public.syms ++++ b/src/libvirt_public.syms +@@ -258,4 +258,10 @@ LIBVIRT_0.6.1 { + virNodeGetSecurityModel; + } LIBVIRT_0.6.0; + ++LIBVIRT_0.6.3 { ++ global: ++ virNodeDeviceCreateXML; ++ virNodeDeviceDestroy; ++} LIBVIRT_0.6.1; ++ + # .... define new API here using predicted next version number .... +-- +1.6.0.6 + diff --git a/docs/api_extension/0002-Step-2-of-8-Define-the-internal-driver-API.patch b/docs/api_extension/0002-Step-2-of-8-Define-the-internal-driver-API.patch new file mode 100644 index 0000000..231cbdf --- /dev/null +++ b/docs/api_extension/0002-Step-2-of-8-Define-the-internal-driver-API.patch @@ -0,0 +1,37 @@ +From b26d7fc2d64e7e6e4d3ea2b43361015d3620d7a6 Mon Sep 17 00:00:00 2001 +From: David Allan <dallan@redhat.com> +Date: Tue, 19 May 2009 16:19:14 -0400 +Subject: [PATCH] Step 2 of 8 Define the internal driver API + +--- + src/driver.h | 7 +++++++ + 1 files changed, 7 insertions(+), 0 deletions(-) + +diff --git a/src/driver.h b/src/driver.h +index 39dc413..c357b76 100644 +--- a/src/driver.h ++++ b/src/driver.h +@@ -684,6 +684,11 @@ typedef int (*virDevMonDeviceListCaps)(virNodeDevicePtr dev, + char **const names, + int maxnames); + ++typedef virNodeDevicePtr (*virDrvNodeDeviceCreateXML)(virConnectPtr conn, ++ const char *xmlDesc, ++ unsigned int flags); ++typedef int (*virDrvNodeDeviceDestroy)(virNodeDevicePtr dev); ++ + /** + * _virDeviceMonitor: + * +@@ -702,6 +707,8 @@ struct _virDeviceMonitor { + virDevMonDeviceGetParent deviceGetParent; + virDevMonDeviceNumOfCaps deviceNumOfCaps; + virDevMonDeviceListCaps deviceListCaps; ++ virDrvNodeDeviceCreateXML deviceCreateXML; ++ virDrvNodeDeviceDestroy deviceDestroy; + }; + + /* +-- +1.6.0.6 + diff --git a/docs/api_extension/0003-Step-3-of-8-Implement-the-public-API.patch b/docs/api_extension/0003-Step-3-of-8-Implement-the-public-API.patch new file mode 100644 index 0000000..079bd06 --- /dev/null +++ b/docs/api_extension/0003-Step-3-of-8-Implement-the-public-API.patch @@ -0,0 +1,120 @@ +From fc585594a207dfb9149e7d3d01c9eb1c79b6d52d Mon Sep 17 00:00:00 2001 +From: David Allan <dallan@redhat.com> +Date: Tue, 19 May 2009 16:22:23 -0400 +Subject: [PATCH] Step 3 of 8 Implement the public API + +--- + src/libvirt.c | 97 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + 1 files changed, 97 insertions(+), 0 deletions(-) + +diff --git a/src/libvirt.c b/src/libvirt.c +index f3d4484..ded18a7 100644 +--- a/src/libvirt.c ++++ b/src/libvirt.c +@@ -7509,6 +7509,103 @@ error: + } + + ++/** ++ * virNodeDeviceCreateXML: ++ * @conn: pointer to the hypervisor connection ++ * @xmlDesc: string containing an XML description of the device to be created ++ * @flags: callers should always pass 0 ++ * ++ * Create a new device on the VM host machine, for example, virtual ++ * HBAs created using vport_create. ++ * ++ * Returns a node device object if successful, NULL in case of failure ++ */ ++virNodeDevicePtr ++virNodeDeviceCreateXML(virConnectPtr conn, ++ const char *xmlDesc, ++ unsigned int flags) ++{ ++ VIR_DEBUG("conn=%p, xmlDesc=%s, flags=%d", conn, xmlDesc, flags); ++ ++ virResetLastError(); ++ ++ if (!VIR_IS_CONNECT(conn)) { ++ virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__); ++ return NULL; ++ } ++ ++ if (conn->flags & VIR_CONNECT_RO) { ++ virLibConnError(conn, VIR_ERR_OPERATION_DENIED, __FUNCTION__); ++ goto error; ++ } ++ ++ if (xmlDesc == NULL) { ++ virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__); ++ goto error; ++ } ++ ++ if (conn->deviceMonitor && ++ conn->deviceMonitor->deviceCreateXML) { ++ virNodeDevicePtr dev = conn->deviceMonitor->deviceCreateXML(conn, xmlDesc, flags); ++ if (dev == NULL) ++ goto error; ++ return dev; ++ } ++ ++ virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__); ++ ++error: ++ /* Copy to connection error object for back compatability */ ++ virSetConnError(conn); ++ return NULL; ++} ++ ++ ++/** ++ * virNodeDeviceDestroy: ++ * @dev: a device object ++ * ++ * Destroy the device object. The virtual device is removed from the host operating system. ++ * This function may require privileged access ++ * ++ * Returns 0 in case of success and -1 in case of failure. ++ */ ++int ++virNodeDeviceDestroy(virNodeDevicePtr dev) ++{ ++ DEBUG("dev=%p", dev); ++ ++ virResetLastError(); ++ ++ if (!VIR_IS_CONNECTED_NODE_DEVICE(dev)) { ++ virLibNodeDeviceError(NULL, VIR_ERR_INVALID_NODE_DEVICE, __FUNCTION__); ++ return (-1); ++ } ++ ++ if (dev->conn->flags & VIR_CONNECT_RO) { ++ virLibConnError(dev->conn, VIR_ERR_OPERATION_DENIED, __FUNCTION__); ++ goto error; ++ } ++ ++ if (dev->conn->deviceMonitor && ++ dev->conn->deviceMonitor->deviceDestroy) { ++ int retval = dev->conn->deviceMonitor->deviceDestroy(dev); ++ if (retval < 0) { ++ goto error; ++ } ++ ++ return 0; ++ } ++ ++ virLibConnError (dev->conn, VIR_ERR_NO_SUPPORT, __FUNCTION__); ++ ++error: ++ /* Copy to connection error object for back compatability */ ++ virSetConnError(dev->conn); ++ return -1; ++} ++ ++ + /* + * Domain Event Notification + */ +-- +1.6.0.6 + diff --git a/docs/api_extension/0004-Step-4-of-8-Define-the-wire-protocol-format.patch b/docs/api_extension/0004-Step-4-of-8-Define-the-wire-protocol-format.patch new file mode 100644 index 0000000..8990263 --- /dev/null +++ b/docs/api_extension/0004-Step-4-of-8-Define-the-wire-protocol-format.patch @@ -0,0 +1,48 @@ +From bce8f1243b0454c0d70e3db832a039d22faab09a Mon Sep 17 00:00:00 2001 +From: David Allan <dallan@redhat.com> +Date: Wed, 20 May 2009 13:58:58 -0400 +Subject: [PATCH] Step 4 of 8 Define the wire protocol format + +--- + qemud/remote_protocol.x | 18 +++++++++++++++++- + 1 files changed, 17 insertions(+), 1 deletions(-) + +diff --git a/qemud/remote_protocol.x b/qemud/remote_protocol.x +index 2d8e6a2..2c79949 100644 +--- a/qemud/remote_protocol.x ++++ b/qemud/remote_protocol.x +@@ -1109,6 +1109,19 @@ struct remote_node_device_reset_args { + remote_nonnull_string name; + }; + ++struct remote_node_device_create_xml_args { ++ remote_nonnull_string xml_desc; ++ int flags; ++}; ++ ++struct remote_node_device_create_xml_ret { ++ remote_nonnull_node_device dev; ++}; ++ ++struct remote_node_device_destroy_args { ++ remote_nonnull_string name; ++}; ++ + + /** + * Events Register/Deregister: +@@ -1270,7 +1283,10 @@ enum remote_procedure { + REMOTE_PROC_NODE_DEVICE_RESET = 120, + + REMOTE_PROC_DOMAIN_GET_SECURITY_LABEL = 121, +- REMOTE_PROC_NODE_GET_SECURITY_MODEL = 122 ++ REMOTE_PROC_NODE_GET_SECURITY_MODEL = 122, ++ ++ REMOTE_PROC_NODE_DEVICE_CREATE_XML = 123, ++ REMOTE_PROC_NODE_DEVICE_DESTROY = 124 + }; + + /* Custom RPC structure. */ +-- +1.6.0.6 + diff --git a/docs/api_extension/0005-Step-5-of-8-Implement-the-RPC-client.patch b/docs/api_extension/0005-Step-5-of-8-Implement-the-RPC-client.patch new file mode 100644 index 0000000..6f87dea --- /dev/null +++ b/docs/api_extension/0005-Step-5-of-8-Implement-the-RPC-client.patch @@ -0,0 +1,85 @@ +From ff272552c297966ace3492aefe91fc830152251a Mon Sep 17 00:00:00 2001 +From: David Allan <dallan@redhat.com> +Date: Tue, 19 May 2009 16:26:12 -0400 +Subject: [PATCH] Step 5 of 8 Implement the RPC client + +--- + src/remote_internal.c | 55 +++++++++++++++++++++++++++++++++++++++++++++++++ + 1 files changed, 55 insertions(+), 0 deletions(-) + +diff --git a/src/remote_internal.c b/src/remote_internal.c +index 4b3afb0..e665ef8 100644 +--- a/src/remote_internal.c ++++ b/src/remote_internal.c +@@ -4978,6 +4978,59 @@ done: + } + + ++static virNodeDevicePtr ++remoteNodeDeviceCreateXML(virConnectPtr conn, ++ const char *xmlDesc, ++ unsigned int flags) ++{ ++ remote_node_device_create_xml_args args; ++ remote_node_device_create_xml_ret ret; ++ virNodeDevicePtr dev = NULL; ++ struct private_data *priv = conn->privateData; ++ ++ remoteDriverLock(priv); ++ ++ memset(&ret, 0, sizeof ret); ++ args.xml_desc = (char *)xmlDesc; ++ args.flags = flags; ++ ++ if (call(conn, priv, 0, REMOTE_PROC_NODE_DEVICE_CREATE_XML, ++ (xdrproc_t) xdr_remote_node_device_create_xml_args, (char *) &args, ++ (xdrproc_t) xdr_remote_node_device_create_xml_ret, (char *) &ret) == -1) ++ goto done; ++ ++ dev = get_nonnull_node_device(conn, ret.dev); ++ xdr_free ((xdrproc_t) xdr_remote_node_device_create_xml_ret, (char *) &ret); ++ ++done: ++ remoteDriverUnlock(priv); ++ return dev; ++} ++ ++static int ++remoteNodeDeviceDestroy(virNodeDevicePtr dev) ++{ ++ int rv = -1; ++ remote_node_device_destroy_args args; ++ struct private_data *priv = dev->conn->privateData; ++ ++ remoteDriverLock(priv); ++ ++ args.name = dev->name; ++ ++ if (call(dev->conn, priv, 0, REMOTE_PROC_NODE_DEVICE_DESTROY, ++ (xdrproc_t) xdr_remote_node_device_destroy_args, (char *) &args, ++ (xdrproc_t) xdr_void, (char *) NULL) == -1) ++ goto done; ++ ++ rv = 0; ++ ++done: ++ remoteDriverUnlock(priv); ++ return rv; ++} ++ ++ + /*----------------------------------------------------------------------*/ + + static int +@@ -6982,6 +7035,8 @@ static virDeviceMonitor dev_monitor = { + .deviceGetParent = remoteNodeDeviceGetParent, + .deviceNumOfCaps = remoteNodeDeviceNumOfCaps, + .deviceListCaps = remoteNodeDeviceListCaps, ++ .deviceCreateXML = remoteNodeDeviceCreateXML, ++ .deviceDestroy = remoteNodeDeviceDestroy + }; + + +-- +1.6.0.6 + diff --git a/docs/api_extension/0006-Step-6-of-8-Implement-the-server-side-dispatcher.patch b/docs/api_extension/0006-Step-6-of-8-Implement-the-server-side-dispatcher.patch new file mode 100644 index 0000000..96df453 --- /dev/null +++ b/docs/api_extension/0006-Step-6-of-8-Implement-the-server-side-dispatcher.patch @@ -0,0 +1,71 @@ +From 4c5166df583459574526841234d61d6ae5be19a0 Mon Sep 17 00:00:00 2001 +From: David Allan <dallan@redhat.com> +Date: Tue, 19 May 2009 16:26:55 -0400 +Subject: [PATCH] Step 6 of 8 Implement the server side dispatcher + +--- + qemud/remote.c | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ + 1 files changed, 48 insertions(+), 0 deletions(-) + +diff --git a/qemud/remote.c b/qemud/remote.c +index e27820f..8d24a3a 100644 +--- a/qemud/remote.c ++++ b/qemud/remote.c +@@ -4323,6 +4323,54 @@ remoteDispatchNodeDeviceReset (struct qemud_server *server ATTRIBUTE_UNUSED, + } + + ++static int ++remoteDispatchNodeDeviceCreateXml(struct qemud_server *server ATTRIBUTE_UNUSED, ++ struct qemud_client *client ATTRIBUTE_UNUSED, ++ virConnectPtr conn, ++ remote_error *rerr, ++ remote_node_device_create_xml_args *args, ++ remote_node_device_create_xml_ret *ret) ++{ ++ virNodeDevicePtr dev; ++ ++ dev = virNodeDeviceCreateXML (conn, args->xml_desc, args->flags); ++ if (dev == NULL) { ++ remoteDispatchConnError(rerr, conn); ++ return -1; ++ } ++ ++ make_nonnull_node_device (&ret->dev, dev); ++ virNodeDeviceFree(dev); ++ ++ return 0; ++} ++ ++ ++static int ++remoteDispatchNodeDeviceDestroy(struct qemud_server *server ATTRIBUTE_UNUSED, ++ struct qemud_client *client ATTRIBUTE_UNUSED, ++ virConnectPtr conn, ++ remote_error *rerr, ++ remote_node_device_destroy_args *args, ++ void *ret ATTRIBUTE_UNUSED) ++{ ++ virNodeDevicePtr dev; ++ ++ dev = virNodeDeviceLookupByName(conn, args->name); ++ if (dev == NULL) { ++ remoteDispatchFormatError(rerr, "%s", _("node_device not found")); ++ return -1; ++ } ++ ++ if (virNodeDeviceDestroy(dev) == -1) { ++ remoteDispatchConnError(rerr, conn); ++ return -1; ++ } ++ ++ return 0; ++} ++ ++ + /************************** + * Async Events + **************************/ +-- +1.6.0.6 + diff --git a/docs/api_extension/0007-Step-7-of-8-Implement-the-driver-methods.patch b/docs/api_extension/0007-Step-7-of-8-Implement-the-driver-methods.patch new file mode 100644 index 0000000..ddd0a41 --- /dev/null +++ b/docs/api_extension/0007-Step-7-of-8-Implement-the-driver-methods.patch @@ -0,0 +1,1172 @@ +From 04d20a662109de6727232eb1213627877bb9662f Mon Sep 17 00:00:00 2001 +From: David Allan <dallan@redhat.com> +Date: Tue, 19 May 2009 16:35:15 -0400 +Subject: [PATCH] Step 7 of 8 Implement the driver methods + +--- + src/Makefile.am | 4 +- + src/node_device.c | 430 +++++++++++++++++++++++++++++++++++++++++++ + src/node_device.h | 13 ++ + src/node_device_conf.c | 136 ++++++++++++-- + src/node_device_conf.h | 22 ++- + src/node_device_hal.c | 5 + + src/node_device_hal.h | 40 ++++ + src/node_device_hal_linux.c | 170 +++++++++++++++++ + src/qemu_driver.c | 2 +- + src/storage_backend.c | 24 +-- + src/xen_unified.c | 2 +- + tests/nodedevxml2xmltest.c | 2 +- + 12 files changed, 810 insertions(+), 40 deletions(-) + create mode 100644 src/node_device_hal.h + create mode 100644 src/node_device_hal_linux.c + +diff --git a/src/Makefile.am b/src/Makefile.am +index fd692b4..39fabce 100644 +--- a/src/Makefile.am ++++ b/src/Makefile.am +@@ -188,7 +188,9 @@ NODE_DEVICE_DRIVER_SOURCES = \ + node_device.c node_device.h + + NODE_DEVICE_DRIVER_HAL_SOURCES = \ +- node_device_hal.c ++ node_device_hal.c \ ++ node_device_hal_linux.c ++ + NODE_DEVICE_DRIVER_DEVKIT_SOURCES = \ + node_device_devkit.c + +diff --git a/src/node_device.c b/src/node_device.c +index b84729f..4f73baf 100644 +--- a/src/node_device.c ++++ b/src/node_device.c +@@ -25,6 +25,8 @@ + + #include <unistd.h> + #include <errno.h> ++#include <fcntl.h> ++#include <time.h> + + #include "virterror_internal.h" + #include "datatypes.h" +@@ -133,6 +135,53 @@ cleanup: + return ret; + } + ++ ++static virNodeDevicePtr ++nodeDeviceLookupByWWN(virConnectPtr conn, ++ const char *wwnn, ++ const char *wwpn) ++{ ++ unsigned int i; ++ virDeviceMonitorStatePtr driver = conn->devMonPrivateData; ++ virNodeDeviceObjListPtr devs = &driver->devs; ++ virNodeDevCapsDefPtr cap = NULL; ++ virNodeDeviceObjPtr obj = NULL; ++ virNodeDevicePtr dev = NULL; ++ ++ nodeDeviceLock(driver); ++ ++ for (i = 0; i < devs->count; i++) { ++ ++ obj = devs->objs[i]; ++ virNodeDeviceObjLock(obj); ++ cap = obj->def->caps; ++ ++ while (cap) { ++ ++ if (cap->type == VIR_NODE_DEV_CAP_SCSI_HOST) { ++ if (cap->data.scsi_host.flags & ++ VIR_NODE_DEV_CAP_FLAG_HBA_FC_HOST) { ++ ++ if (STREQ(cap->data.scsi_host.wwnn, wwnn) && ++ STREQ(cap->data.scsi_host.wwpn, wwpn)) { ++ dev = virGetNodeDevice(conn, obj->def->name); ++ virNodeDeviceObjUnlock(obj); ++ goto out; ++ } ++ } ++ } ++ cap = cap->next; ++ } ++ ++ virNodeDeviceObjUnlock(obj); ++ } ++ ++out: ++ nodeDeviceUnlock(driver); ++ return dev; ++} ++ ++ + static char *nodeDeviceDumpXML(virNodeDevicePtr dev, + unsigned int flags ATTRIBUTE_UNUSED) + { +@@ -258,6 +307,385 @@ cleanup: + } + + ++static int ++nodeDeviceVportCreateDelete(virConnectPtr conn, ++ const int parent_host, ++ const char *wwpn, ++ const char *wwnn, ++ int operation) ++{ ++ int fd = -1; ++ int retval = 0; ++ char *operation_path = NULL, *vport_name = NULL; ++ const char *operation_file = NULL; ++ size_t towrite = 0; ++ unsigned int written = 0; ++ ++ switch (operation) { ++ case VPORT_CREATE: ++ operation_file = LINUX_SYSFS_VPORT_CREATE_POSTFIX; ++ break; ++ case VPORT_DELETE: ++ operation_file = LINUX_SYSFS_VPORT_DELETE_POSTFIX; ++ break; ++ default: ++ virNodeDeviceReportError(conn, VIR_ERR_INTERNAL_ERROR, ++ _("Invalid vport operation (%d)"), operation); ++ retval = -1; ++ goto cleanup; ++ break; ++ } ++ ++ if (virAsprintf(&operation_path, ++ "%shost%d%s", ++ LINUX_SYSFS_FC_HOST_PREFIX, ++ parent_host, ++ operation_file) < 0) { ++ ++ virReportOOMError(conn); ++ retval = -1; ++ goto cleanup; ++ } ++ ++ VIR_DEBUG(_("Vport operation path is '%s'"), operation_path); ++ ++ fd = open(operation_path, O_WRONLY); ++ ++ if (fd < 0) { ++ virReportSystemError(conn, errno, ++ _("Could not open '%s' for vport operation"), ++ operation_path); ++ retval = -1; ++ goto cleanup; ++ } ++ ++ if (virAsprintf(&vport_name, ++ "%s:%s", ++ wwpn, ++ wwnn) < 0) { ++ ++ virReportOOMError(conn); ++ retval = -1; ++ goto cleanup; ++ } ++ ++ towrite = strlen(vport_name); ++ written = safewrite(fd, vport_name, towrite); ++ if (written != towrite) { ++ virReportSystemError(conn, errno, ++ _("Write of '%s' to '%s' during " ++ "vport create/delete failed " ++ "(towrite: %lu written: %d)"), ++ vport_name, operation_path, ++ towrite, written); ++ retval = -1; ++ } ++ ++cleanup: ++ if (fd != -1) { ++ close(fd); ++ } ++ VIR_FREE(vport_name); ++ VIR_FREE(operation_path); ++ VIR_DEBUG("%s", _("Vport operation complete")); ++ return retval; ++} ++ ++ ++static int ++get_wwns(virConnectPtr conn, ++ virNodeDeviceDefPtr def, ++ char **wwnn, ++ char **wwpn) ++{ ++ virNodeDevCapsDefPtr cap = NULL; ++ int ret = 0; ++ ++ cap = def->caps; ++ while (cap != NULL) { ++ if (cap->type == VIR_NODE_DEV_CAP_SCSI_HOST && ++ cap->data.scsi_host.flags & VIR_NODE_DEV_CAP_FLAG_HBA_FC_HOST) { ++ *wwnn = strdup(cap->data.scsi_host.wwnn); ++ *wwpn = strdup(cap->data.scsi_host.wwpn); ++ break; ++ } ++ ++ cap = cap->next; ++ } ++ ++ if (cap == NULL) { ++ virNodeDeviceReportError(conn, VIR_ERR_NO_SUPPORT, ++ "%s", _("Device is not a fibre channel HBA")); ++ ret = -1; ++ } ++ ++ if (*wwnn == NULL || *wwpn == NULL) { ++ /* Free the other one, if allocated... */ ++ VIR_FREE(wwnn); ++ VIR_FREE(wwpn); ++ ret = -1; ++ virReportOOMError(conn); ++ } ++ ++ return ret; ++} ++ ++ ++static int ++get_parent_host(virConnectPtr conn, ++ virDeviceMonitorStatePtr driver, ++ const char *dev_name, ++ const char *parent_name, ++ int *parent_host) ++{ ++ virNodeDeviceObjPtr parent = NULL; ++ virNodeDevCapsDefPtr cap = NULL; ++ int ret = 0; ++ ++ parent = virNodeDeviceFindByName(&driver->devs, parent_name); ++ if (parent == NULL) { ++ virNodeDeviceReportError(conn, VIR_ERR_INVALID_NODE_DEVICE, ++ _("Could not find parent device for '%s'"), ++ dev_name); ++ ret = -1; ++ goto out; ++ } ++ ++ cap = parent->def->caps; ++ while (cap != NULL) { ++ if (cap->type == VIR_NODE_DEV_CAP_SCSI_HOST && ++ (cap->data.scsi_host.flags & ++ VIR_NODE_DEV_CAP_FLAG_HBA_VPORT_OPS)) { ++ *parent_host = cap->data.scsi_host.host; ++ break; ++ } ++ ++ cap = cap->next; ++ } ++ ++ if (cap == NULL) { ++ virNodeDeviceReportError(conn, VIR_ERR_INVALID_NODE_DEVICE, ++ _("Device %s is not capable of vport operations"), ++ parent->def->name); ++ ret = -1; ++ } ++ ++ virNodeDeviceObjUnlock(parent); ++ ++out: ++ return ret; ++} ++ ++ ++static int ++get_time(virConnectPtr conn, time_t *t) ++{ ++ int ret = 0; ++ ++ *t = time(NULL); ++ if (*t == (time_t)-1) { ++ virNodeDeviceReportError(conn, VIR_ERR_INTERNAL_ERROR, ++ "%s", _("Could not get current time")); ++ ++ *t = 0; ++ ret = -1; ++ } ++ ++ return ret; ++} ++ ++ ++/* When large numbers of devices are present on the host, it's ++ * possible for udev not to realize that it has work to do before we ++ * get here. We thus keep trying to find the new device we just ++ * created for up to LINUX_NEW_DEVICE_WAIT_TIME. Note that udev's ++ * default settle time is 180 seconds, so once udev realizes that it ++ * has work to do, it might take that long for the udev wait to ++ * return. Thus the total maximum time for this function to return is ++ * the udev settle time plus LINUX_NEW_DEVICE_WAIT_TIME. ++ * ++ * This whole area is a race, but if we retry the udev wait for ++ * LINUX_NEW_DEVICE_WAIT_TIME seconds and there's still no device, ++ * it's probably safe to assume it's not going to appear. ++ */ ++static virNodeDevicePtr ++find_new_device(virConnectPtr conn, const char *wwnn, const char *wwpn) ++{ ++ virDeviceMonitorStatePtr driver = conn->devMonPrivateData; ++ virNodeDevicePtr dev = NULL; ++ time_t start = 0, now = 0; ++ ++ /* The thread that creates the device takes the driver lock, so we ++ * must release it in order to allow the device to be created. ++ * We're not doing anything with the driver pointer at this point, ++ * so it's safe to release it, assuming that the pointer itself ++ * doesn't become invalid. */ ++ nodeDeviceUnlock(driver); ++ ++ get_time(conn, &start); ++ ++ while ((now - start) < LINUX_NEW_DEVICE_WAIT_TIME) { ++ ++ virNodeDeviceWaitForDevices(conn); ++ ++ dev = nodeDeviceLookupByWWN(conn, wwnn, wwpn); ++ ++ if (dev != NULL) { ++ break; ++ } ++ ++ sleep(5); ++ if (get_time(conn, &now) == -1) { ++ break; ++ } ++ } ++ ++ nodeDeviceLock(driver); ++ ++ return dev; ++} ++ ++static virNodeDevicePtr ++nodeDeviceCreateXML(virConnectPtr conn, ++ const char *xmlDesc, ++ unsigned int flags ATTRIBUTE_UNUSED) ++{ ++ virDeviceMonitorStatePtr driver = conn->devMonPrivateData; ++ virNodeDeviceDefPtr def = NULL; ++ char *wwnn = NULL, *wwpn = NULL; ++ int parent_host = -1; ++ virNodeDevicePtr dev = NULL; ++ ++ nodeDeviceLock(driver); ++ ++ def = virNodeDeviceDefParseString(conn, xmlDesc, CREATE_DEVICE); ++ if (def == NULL) { ++ goto cleanup; ++ } ++ ++ if (get_wwns(conn, def, &wwnn, &wwpn) == -1) { ++ goto cleanup; ++ } ++ ++ if (get_parent_host(conn, ++ driver, ++ def->name, ++ def->parent, ++ &parent_host) == -1) { ++ goto cleanup; ++ } ++ ++ if (nodeDeviceVportCreateDelete(conn, ++ parent_host, ++ wwpn, ++ wwnn, ++ VPORT_CREATE) == -1) { ++ goto cleanup; ++ } ++ ++ dev = find_new_device(conn, wwnn, wwpn); ++ /* We don't check the return value, because one way or another, ++ * we're returning what we get... */ ++ ++ if (dev == NULL) { ++ virNodeDeviceReportError(conn, VIR_ERR_NO_NODE_DEVICE, NULL); ++ } ++ ++cleanup: ++ nodeDeviceUnlock(driver); ++ virNodeDeviceDefFree(def); ++ VIR_FREE(wwnn); ++ VIR_FREE(wwpn); ++ return dev; ++} ++ ++ ++static int ++nodeDeviceDestroy(virNodeDevicePtr dev) ++{ ++ int ret = 0; ++ virDeviceMonitorStatePtr driver = dev->conn->devMonPrivateData; ++ virNodeDeviceObjPtr obj = NULL; ++ char *parent_name = NULL, *wwnn = NULL, *wwpn = NULL; ++ int parent_host = -1; ++ ++ nodeDeviceLock(driver); ++ obj = virNodeDeviceFindByName(&driver->devs, dev->name); ++ nodeDeviceUnlock(driver); ++ ++ if (!obj) { ++ virNodeDeviceReportError(dev->conn, VIR_ERR_NO_NODE_DEVICE, NULL); ++ goto out; ++ } ++ ++ if (get_wwns(dev->conn, obj->def, &wwnn, &wwpn) == -1) { ++ goto out; ++ } ++ ++ parent_name = strdup(obj->def->parent); ++ ++ /* get_parent_host will cause the device object's lock to be ++ * taken, so we have to dup the parent's name and drop the lock ++ * before calling it. We don't need the reference to the object ++ * any more once we have the parent's name. */ ++ virNodeDeviceObjUnlock(obj); ++ obj = NULL; ++ ++ if (parent_name == NULL) { ++ virReportOOMError(dev->conn); ++ goto out; ++ } ++ ++ if (get_parent_host(dev->conn, ++ driver, ++ dev->name, ++ parent_name, ++ &parent_host) == -1) { ++ goto out; ++ } ++ ++ if (nodeDeviceVportCreateDelete(dev->conn, ++ parent_host, ++ wwpn, ++ wwnn, ++ VPORT_DELETE) == -1) { ++ goto out; ++ } ++ ++out: ++ VIR_FREE(parent_name); ++ VIR_FREE(wwnn); ++ VIR_FREE(wwpn); ++ return ret; ++} ++ ++ ++#if defined(UDEVADM) || defined(UDEVSETTLE) ++void virNodeDeviceWaitForDevices(virConnectPtr conn) ++{ ++#ifdef UDEVADM ++ const char *const settleprog[] = { UDEVADM, "settle", NULL }; ++#else ++ const char *const settleprog[] = { UDEVSETTLE, NULL }; ++#endif ++ int exitstatus; ++ ++ if (access(settleprog[0], X_OK) != 0) ++ return; ++ ++ /* ++ * NOTE: we ignore errors here; this is just to make sure that any device ++ * nodes that are being created finish before we try to scan them. ++ * If this fails for any reason, we still have the backup of polling for ++ * 5 seconds for device nodes. ++ */ ++ virRun(conn, settleprog, &exitstatus); ++} ++#else ++void virNodeDeviceWaitForDevices(virConnectPtr conn ATTRIBUTE_UNUSED) {} ++#endif ++ ++ + void registerCommonNodeFuncs(virDeviceMonitorPtr driver) + { + driver->numOfDevices = nodeNumOfDevices; +@@ -267,6 +695,8 @@ void registerCommonNodeFuncs(virDeviceMonitorPtr driver) + driver->deviceGetParent = nodeDeviceGetParent; + driver->deviceNumOfCaps = nodeDeviceNumOfCaps; + driver->deviceListCaps = nodeDeviceListCaps; ++ driver->deviceCreateXML = nodeDeviceCreateXML; ++ driver->deviceDestroy = nodeDeviceDestroy; + } + + +diff --git a/src/node_device.h b/src/node_device.h +index 9496120..882ba0f 100644 +--- a/src/node_device.h ++++ b/src/node_device.h +@@ -28,6 +28,17 @@ + #include "driver.h" + #include "node_device_conf.h" + ++#define LINUX_SYSFS_SCSI_HOST_PREFIX "/sys/class/scsi_host" ++#define LINUX_SYSFS_SCSI_HOST_POSTFIX "device" ++#define LINUX_SYSFS_FC_HOST_PREFIX "/sys/class/fc_host/" ++ ++#define VPORT_CREATE 0 ++#define VPORT_DELETE 1 ++#define LINUX_SYSFS_VPORT_CREATE_POSTFIX "/vport_create" ++#define LINUX_SYSFS_VPORT_DELETE_POSTFIX "/vport_delete" ++ ++#define LINUX_NEW_DEVICE_WAIT_TIME 60 ++ + #ifdef HAVE_HAL + int halNodeRegister(void); + #endif +@@ -42,4 +53,6 @@ void registerCommonNodeFuncs(virDeviceMonitorPtr mon); + + int nodedevRegister(void); + ++void virNodeDeviceWaitForDevices(virConnectPtr conn); ++ + #endif /* __VIR_NODE_DEVICE_H__ */ +diff --git a/src/node_device_conf.c b/src/node_device_conf.c +index 6e04112..5b35b60 100644 +--- a/src/node_device_conf.c ++++ b/src/node_device_conf.c +@@ -53,9 +53,34 @@ VIR_ENUM_IMPL(virNodeDevNetCap, VIR_NODE_DEV_CAP_NET_LAST, + "80203", + "80211") + ++VIR_ENUM_IMPL(virNodeDevHBACap, VIR_NODE_DEV_CAP_HBA_LAST, ++ "fc_host", ++ "vport_ops") + + #define virNodeDeviceLog(msg...) fprintf(stderr, msg) + ++static int ++virNodeDevCapsDefParseString(virConnectPtr conn, ++ const char *xpath, ++ xmlXPathContextPtr ctxt, ++ char **string, ++ virNodeDeviceDefPtr def, ++ const char *missing_error_fmt) ++{ ++ char *s; ++ ++ s = virXPathString(conn, xpath, ctxt); ++ if (s == NULL) { ++ virNodeDeviceReportError(conn, VIR_ERR_INTERNAL_ERROR, ++ missing_error_fmt, ++ def->name); ++ return -1; ++ } ++ ++ *string = s; ++ return 0; ++} ++ + virNodeDeviceObjPtr virNodeDeviceFindByName(const virNodeDeviceObjListPtr devs, + const char *name) + { +@@ -302,6 +327,18 @@ char *virNodeDeviceDefFormat(virConnectPtr conn, + case VIR_NODE_DEV_CAP_SCSI_HOST: + virBufferVSprintf(&buf, " <host>%d</host>\n", + data->scsi_host.host); ++ if (data->scsi_host.flags & VIR_NODE_DEV_CAP_FLAG_HBA_FC_HOST) { ++ virBufferAddLit(&buf, " <capability type='fc_host'>\n"); ++ virBufferVSprintf(&buf, ++ " <wwnn>%s</wwnn>\n", data->scsi_host.wwnn); ++ virBufferVSprintf(&buf, ++ " <wwpn>%s</wwpn>\n", data->scsi_host.wwpn); ++ virBufferAddLit(&buf, " </capability>\n"); ++ } ++ if (data->scsi_host.flags & VIR_NODE_DEV_CAP_FLAG_HBA_VPORT_OPS) { ++ virBufferAddLit(&buf, " <capability type='vport_ops' />\n"); ++ } ++ + break; + case VIR_NODE_DEV_CAP_SCSI: + virBufferVSprintf(&buf, " <host>%d</host>\n", data->scsi.host); +@@ -561,26 +598,91 @@ virNodeDevCapScsiHostParseXML(virConnectPtr conn, + xmlXPathContextPtr ctxt, + virNodeDeviceDefPtr def, + xmlNodePtr node, +- union _virNodeDevCapData *data) ++ union _virNodeDevCapData *data, ++ int create) + { +- xmlNodePtr orignode; +- int ret = -1; ++ xmlNodePtr orignode, *nodes = NULL; ++ int ret = -1, n = 0, i; ++ char *type = NULL; + + orignode = ctxt->node; + ctxt->node = node; + +- if (virNodeDevCapsDefParseULong(conn, "number(./host[1])", ctxt, ++ if (create == EXISTING_DEVICE && ++ virNodeDevCapsDefParseULong(conn, "number(./host[1])", ctxt, + &data->scsi_host.host, def, + _("no SCSI host ID supplied for '%s'"), +- _("invalid SCSI host ID supplied for '%s'")) < 0) ++ _("invalid SCSI host ID supplied for '%s'")) < 0) { + goto out; ++ } ++ ++ if ((n = virXPathNodeSet(conn, "./capability", ctxt, &nodes)) < 0) { ++ virNodeDeviceReportError(conn, VIR_ERR_INTERNAL_ERROR, ++ _("error parsing SCSI host capabilities for '%s'"), ++ def->name); ++ goto out; ++ } ++ ++ for (i = 0 ; i < n ; i++) { ++ type = virXMLPropString(nodes[i], "type"); ++ ++ if (!type) { ++ virNodeDeviceReportError(conn, VIR_ERR_INTERNAL_ERROR, ++ _("missing SCSI host capability type for '%s'"), ++ def->name); ++ goto out; ++ } ++ ++ if (STREQ(type, "vport_ops")) { ++ ++ data->scsi_host.flags |= VIR_NODE_DEV_CAP_FLAG_HBA_VPORT_OPS; ++ ++ } else if (STREQ(type, "fc_host")) { ++ ++ xmlNodePtr orignode2; ++ ++ data->scsi_host.flags |= VIR_NODE_DEV_CAP_FLAG_HBA_FC_HOST; ++ ++ orignode2 = ctxt->node; ++ ctxt->node = nodes[i]; ++ ++ if (virNodeDevCapsDefParseString(conn, "string(./wwnn[1])", ++ ctxt, ++ &data->scsi_host.wwnn, ++ def, ++ _("no WWNN supplied for '%s'")) < 0) { ++ goto out; ++ } ++ ++ if (virNodeDevCapsDefParseString(conn, "string(./wwpn[1])", ++ ctxt, ++ &data->scsi_host.wwpn, ++ def, ++ _("no WWPN supplied for '%s'")) < 0) { ++ goto out; ++ } ++ ++ ctxt->node = orignode2; ++ ++ } else { ++ virNodeDeviceReportError(conn, VIR_ERR_INTERNAL_ERROR, ++ _("unknown SCSI host capability type '%s' for '%s'"), ++ type, def->name); ++ goto out; ++ } ++ ++ VIR_FREE(type); ++ } + + ret = 0; ++ + out: ++ VIR_FREE(type); + ctxt->node = orignode; + return ret; + } + ++ + static int + virNodeDevCapNetParseXML(virConnectPtr conn, + xmlXPathContextPtr ctxt, +@@ -848,7 +950,8 @@ static virNodeDevCapsDefPtr + virNodeDevCapsDefParseXML(virConnectPtr conn, + xmlXPathContextPtr ctxt, + virNodeDeviceDefPtr def, +- xmlNodePtr node) ++ xmlNodePtr node, ++ int create) + { + virNodeDevCapsDefPtr caps; + char *tmp; +@@ -892,7 +995,7 @@ virNodeDevCapsDefParseXML(virConnectPtr conn, + ret = virNodeDevCapNetParseXML(conn, ctxt, def, node, &caps->data); + break; + case VIR_NODE_DEV_CAP_SCSI_HOST: +- ret = virNodeDevCapScsiHostParseXML(conn, ctxt, def, node, &caps->data); ++ ret = virNodeDevCapScsiHostParseXML(conn, ctxt, def, node, &caps->data, create); + break; + case VIR_NODE_DEV_CAP_SCSI: + ret = virNodeDevCapScsiParseXML(conn, ctxt, def, node, &caps->data); +@@ -918,7 +1021,7 @@ error: + } + + static virNodeDeviceDefPtr +-virNodeDeviceDefParseXML(virConnectPtr conn, xmlXPathContextPtr ctxt) ++virNodeDeviceDefParseXML(virConnectPtr conn, xmlXPathContextPtr ctxt, int create) + { + virNodeDeviceDefPtr def; + virNodeDevCapsDefPtr *next_cap; +@@ -931,7 +1034,12 @@ virNodeDeviceDefParseXML(virConnectPtr conn, xmlXPathContextPtr ctxt) + } + + /* Extract device name */ +- def->name = virXPathString(conn, "string(./name[1])", ctxt); ++ if (create == EXISTING_DEVICE) { ++ def->name = virXPathString(conn, "string(./name[1])", ctxt); ++ } else { ++ def->name = strdup("new device"); ++ } ++ + if (!def->name) { + virNodeDeviceReportError(conn, VIR_ERR_NO_NAME, NULL); + goto error; +@@ -951,7 +1059,7 @@ virNodeDeviceDefParseXML(virConnectPtr conn, xmlXPathContextPtr ctxt) + + next_cap = &def->caps; + for (i = 0 ; i < n ; i++) { +- *next_cap = virNodeDevCapsDefParseXML(conn, ctxt, def, nodes[i]); ++ *next_cap = virNodeDevCapsDefParseXML(conn, ctxt, def, nodes[i], create); + if (!*next_cap) { + VIR_FREE(nodes); + goto error; +@@ -969,7 +1077,7 @@ virNodeDeviceDefParseXML(virConnectPtr conn, xmlXPathContextPtr ctxt) + } + + static virNodeDeviceDefPtr +-virNodeDeviceDefParseNode(virConnectPtr conn, xmlDocPtr xml, xmlNodePtr root) ++virNodeDeviceDefParseNode(virConnectPtr conn, xmlDocPtr xml, xmlNodePtr root, int create) + { + xmlXPathContextPtr ctxt = NULL; + virNodeDeviceDefPtr def = NULL; +@@ -987,7 +1095,7 @@ virNodeDeviceDefParseNode(virConnectPtr conn, xmlDocPtr xml, xmlNodePtr root) + } + + ctxt->node = root; +- def = virNodeDeviceDefParseXML(conn, ctxt); ++ def = virNodeDeviceDefParseXML(conn, ctxt, create); + + cleanup: + xmlXPathFreeContext(ctxt); +@@ -1015,7 +1123,7 @@ catchXMLError(void *ctx, const char *msg ATTRIBUTE_UNUSED, ...) + } + + virNodeDeviceDefPtr +-virNodeDeviceDefParseString(virConnectPtr conn, const char *str) ++virNodeDeviceDefParseString(virConnectPtr conn, const char *str, int create) + { + xmlParserCtxtPtr pctxt; + xmlDocPtr xml = NULL; +@@ -1046,7 +1154,7 @@ virNodeDeviceDefParseString(virConnectPtr conn, const char *str) + goto cleanup; + } + +- def = virNodeDeviceDefParseNode(conn, xml, root); ++ def = virNodeDeviceDefParseNode(conn, xml, root, create); + + cleanup: + xmlFreeParserCtxt(pctxt); +diff --git a/src/node_device_conf.h b/src/node_device_conf.h +index 26e5558..62b4e71 100644 +--- a/src/node_device_conf.h ++++ b/src/node_device_conf.h +@@ -28,6 +28,9 @@ + #include "util.h" + #include "threads.h" + ++#define CREATE_DEVICE 1 ++#define EXISTING_DEVICE 0 ++ + enum virNodeDevCapType { + /* Keep in sync with VIR_ENUM_IMPL in node_device_conf.c */ + VIR_NODE_DEV_CAP_SYSTEM, /* System capability */ +@@ -48,8 +51,16 @@ enum virNodeDevNetCapType { + VIR_NODE_DEV_CAP_NET_LAST + }; + ++enum virNodeDevHBACapType { ++ /* Keep in sync with VIR_ENUM_IMPL in node_device_conf.c */ ++ VIR_NODE_DEV_CAP_HBA_FC_HOST, /* fibre channel HBA */ ++ VIR_NODE_DEV_CAP_HBA_VPORT_OPS, /* capable of vport operations */ ++ VIR_NODE_DEV_CAP_HBA_LAST ++}; ++ + VIR_ENUM_DECL(virNodeDevCap) + VIR_ENUM_DECL(virNodeDevNetCap) ++VIR_ENUM_DECL(virNodeDevHBACap) + + enum virNodeDevStorageCapFlags { + VIR_NODE_DEV_CAP_STORAGE_REMOVABLE = (1 << 0), +@@ -57,6 +68,11 @@ enum virNodeDevStorageCapFlags { + VIR_NODE_DEV_CAP_STORAGE_HOTPLUGGABLE = (1 << 2), + }; + ++enum virNodeDevScsiHostCapFlags { ++ VIR_NODE_DEV_CAP_FLAG_HBA_FC_HOST = (1 << 0), ++ VIR_NODE_DEV_CAP_FLAG_HBA_VPORT_OPS = (1 << 1), ++}; ++ + typedef struct _virNodeDevCapsDef virNodeDevCapsDef; + typedef virNodeDevCapsDef *virNodeDevCapsDefPtr; + struct _virNodeDevCapsDef { +@@ -108,6 +124,9 @@ struct _virNodeDevCapsDef { + } net; + struct { + unsigned host; ++ char *wwnn; ++ char *wwpn; ++ unsigned flags; + } scsi_host; + struct { + unsigned host; +@@ -185,7 +204,8 @@ char *virNodeDeviceDefFormat(virConnectPtr conn, + const virNodeDeviceDefPtr def); + + virNodeDeviceDefPtr virNodeDeviceDefParseString(virConnectPtr conn, +- const char *str); ++ const char *str, ++ int create); + + void virNodeDeviceDefFree(virNodeDeviceDefPtr def); + +diff --git a/src/node_device_hal.c b/src/node_device_hal.c +index b214f60..5927ba1 100644 +--- a/src/node_device_hal.c ++++ b/src/node_device_hal.c +@@ -28,6 +28,7 @@ + #include <libhal.h> + + #include "node_device_conf.h" ++#include "node_device_hal.h" + #include "virterror_internal.h" + #include "driver.h" + #include "datatypes.h" +@@ -37,6 +38,8 @@ + #include "logging.h" + #include "node_device.h" + ++#define VIR_FROM_THIS VIR_FROM_NODEDEV ++ + /* + * Host device enumeration (HAL implementation) + */ +@@ -215,6 +218,8 @@ static int gather_scsi_host_cap(LibHalContext *ctx, const char *udi, + union _virNodeDevCapData *d) + { + (void)get_int_prop(ctx, udi, "scsi_host.host", (int *)&d->scsi_host.host); ++ (void)check_fc_host(d); ++ (void)check_vport_capable(d); + return 0; + } + +diff --git a/src/node_device_hal.h b/src/node_device_hal.h +new file mode 100644 +index 0000000..0b4a2ef +--- /dev/null ++++ b/src/node_device_hal.h +@@ -0,0 +1,40 @@ ++/* ++ * node_device_hal.h: node device enumeration - HAL-based implementation ++ * ++ * Copyright (C) 2009 Red Hat, Inc. ++ * ++ * This library is free software; you can redistribute it and/or ++ * modify it under the terms of the GNU Lesser General Public ++ * License as published by the Free Software Foundation; either ++ * version 2.1 of the License, or (at your option) any later version. ++ * ++ * This library is distributed in the hope that it will be useful, ++ * but WITHOUT ANY WARRANTY; without even the implied warranty of ++ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU ++ * Lesser General Public License for more details. ++ * ++ * You should have received a copy of the GNU Lesser General Public ++ * License along with this library; if not, write to the Free Software ++ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA ++ * ++ */ ++ ++#ifndef __VIR_NODE_DEVICE_HAL_H__ ++#define __VIR_NODE_DEVICE_HAL_H__ ++ ++#ifdef __linux__ ++ ++#define check_fc_host(d) check_fc_host_linux(d) ++int check_fc_host_linux(union _virNodeDevCapData *d); ++ ++#define check_vport_capable(d) check_vport_capable_linux(d) ++int check_vport_capable_linux(union _virNodeDevCapData *d); ++ ++#else /* __linux__ */ ++ ++#define check_fc_host(d) ++#define check_vport_capable(d) ++ ++#endif /* __linux__ */ ++ ++#endif /* __VIR_NODE_DEVICE_HAL_H__ */ +diff --git a/src/node_device_hal_linux.c b/src/node_device_hal_linux.c +new file mode 100644 +index 0000000..1deb6d2 +--- /dev/null ++++ b/src/node_device_hal_linux.c +@@ -0,0 +1,170 @@ ++/* ++ * node_device_hal_linuc.c: Linux specific code to gather device data ++ * not available through HAL. ++ * ++ * Copyright (C) 2009 Red Hat, Inc. ++ * ++ * This library is free software; you can redistribute it and/or ++ * modify it under the terms of the GNU Lesser General Public ++ * License as published by the Free Software Foundation; either ++ * version 2.1 of the License, or (at your option) any later version. ++ * ++ * This library is distributed in the hope that it will be useful, ++ * but WITHOUT ANY WARRANTY; without even the implied warranty of ++ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU ++ * Lesser General Public License for more details. ++ * ++ * You should have received a copy of the GNU Lesser General Public ++ * License along with this library; if not, write to the Free Software ++ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA ++ * ++ */ ++ ++#include <config.h> ++ ++#include <fcntl.h> ++ ++#include "node_device.h" ++#include "node_device_hal.h" ++#include "virterror_internal.h" ++#include "memory.h" ++#include "logging.h" ++ ++#define VIR_FROM_THIS VIR_FROM_NODEDEV ++ ++#ifdef __linux__ ++ ++int check_fc_host_linux(union _virNodeDevCapData *d) ++{ ++ char *sysfs_path = NULL; ++ char *wwnn_path = NULL; ++ char *wwpn_path = NULL; ++ char *p = NULL; ++ int fd = -1; ++ char buf[64]; ++ struct stat st; ++ ++ VIR_DEBUG(_("Checking if host%d is an FC HBA"), d->scsi_host.host); ++ ++ if (virAsprintf(&sysfs_path, "%s/host%d", ++ LINUX_SYSFS_FC_HOST_PREFIX, ++ d->scsi_host.host) < 0) { ++ virReportOOMError(NULL); ++ goto out; ++ } ++ ++ if (stat(sysfs_path, &st) != 0) { ++ /* Not an FC HBA */ ++ goto out; ++ } ++ ++ d->scsi_host.flags |= VIR_NODE_DEV_CAP_FLAG_HBA_FC_HOST; ++ ++ if (virAsprintf(&wwnn_path, "%s/node_name", ++ sysfs_path) < 0) { ++ virReportOOMError(NULL); ++ goto out; ++ } ++ ++ if ((fd = open(wwnn_path, O_RDONLY)) < 0) { ++ goto out; ++ } ++ ++ memset(buf, 0, sizeof(buf)); ++ if (saferead(fd, buf, sizeof(buf)) < 0) { ++ goto out; ++ } ++ ++ close(fd); ++ fd = -1; ++ ++ p = strstr(buf, "0x"); ++ if (p != NULL) { ++ p += strlen("0x"); ++ } else { ++ p = buf; ++ } ++ ++ d->scsi_host.wwnn = strndup(p, sizeof(buf)); ++ if (d->scsi_host.wwnn == NULL) { ++ virReportOOMError(NULL); ++ goto out; ++ } ++ ++ p = strchr(d->scsi_host.wwnn, '\n'); ++ if (p != NULL) { ++ *p = '\0'; ++ } ++ ++ if (virAsprintf(&wwpn_path, "%s/port_name", ++ sysfs_path) < 0) { ++ virReportOOMError(NULL); ++ goto out; ++ } ++ ++ if ((fd = open(wwpn_path, O_RDONLY)) < 0) { ++ goto out; ++ } ++ ++ memset(buf, 0, sizeof(buf)); ++ if (saferead(fd, buf, sizeof(buf)) < 0) { ++ goto out; ++ } ++ ++ close(fd); ++ fd = -1; ++ ++ p = strstr(buf, "0x"); ++ if (p != NULL) { ++ p += strlen("0x"); ++ } else { ++ p = buf; ++ } ++ ++ d->scsi_host.wwpn = strndup(p, sizeof(buf)); ++ if (d->scsi_host.wwpn == NULL) { ++ virReportOOMError(NULL); ++ goto out; ++ } ++ ++ p = strchr(d->scsi_host.wwpn, '\n'); ++ if (p != NULL) { ++ *p = '\0'; ++ } ++ ++out: ++ if (fd != -1) { ++ close(fd); ++ } ++ VIR_FREE(sysfs_path); ++ VIR_FREE(wwnn_path); ++ VIR_FREE(wwpn_path); ++ return 0; ++} ++ ++ ++int check_vport_capable_linux(union _virNodeDevCapData *d) ++{ ++ char *sysfs_path = NULL; ++ struct stat st; ++ ++ if (virAsprintf(&sysfs_path, "%s/host%d/vport_create", ++ LINUX_SYSFS_FC_HOST_PREFIX, ++ d->scsi_host.host) < 0) { ++ virReportOOMError(NULL); ++ goto out; ++ } ++ ++ if (stat(sysfs_path, &st) != 0) { ++ /* Not a vport capable HBA */ ++ goto out; ++ } ++ ++ d->scsi_host.flags |= VIR_NODE_DEV_CAP_FLAG_HBA_VPORT_OPS; ++ ++out: ++ VIR_FREE(sysfs_path); ++ return 0; ++} ++ ++#endif /* __linux__ */ +diff --git a/src/qemu_driver.c b/src/qemu_driver.c +index bd60b29..057e97b 100644 +--- a/src/qemu_driver.c ++++ b/src/qemu_driver.c +@@ -5089,7 +5089,7 @@ qemudNodeDeviceGetPciInfo (virNodeDevicePtr dev, + if (!xml) + goto out; + +- def = virNodeDeviceDefParseString(dev->conn, xml); ++ def = virNodeDeviceDefParseString(dev->conn, xml, EXISTING_DEVICE); + if (!def) + goto out; + +diff --git a/src/storage_backend.c b/src/storage_backend.c +index b154140..74759cf 100644 +--- a/src/storage_backend.c ++++ b/src/storage_backend.c +@@ -46,6 +46,7 @@ + #include "virterror_internal.h" + #include "util.h" + #include "memory.h" ++#include "node_device.h" + + #include "storage_backend.h" + +@@ -245,30 +246,11 @@ virStorageBackendUpdateVolTargetInfoFD(virConnectPtr conn, + return 0; + } + +-#if defined(UDEVADM) || defined(UDEVSETTLE) + void virStorageBackendWaitForDevices(virConnectPtr conn) + { +-#ifdef UDEVADM +- const char *const settleprog[] = { UDEVADM, "settle", NULL }; +-#else +- const char *const settleprog[] = { UDEVSETTLE, NULL }; +-#endif +- int exitstatus; +- +- if (access(settleprog[0], X_OK) != 0) +- return; +- +- /* +- * NOTE: we ignore errors here; this is just to make sure that any device +- * nodes that are being created finish before we try to scan them. +- * If this fails for any reason, we still have the backup of polling for +- * 5 seconds for device nodes. +- */ +- virRun(conn, settleprog, &exitstatus); ++ virNodeDeviceWaitForDevices(conn); ++ return; + } +-#else +-void virStorageBackendWaitForDevices(virConnectPtr conn ATTRIBUTE_UNUSED) {} +-#endif + + /* + * Given a volume path directly in /dev/XXX, iterate over the +diff --git a/src/xen_unified.c b/src/xen_unified.c +index e708980..8da4e23 100644 +--- a/src/xen_unified.c ++++ b/src/xen_unified.c +@@ -1439,7 +1439,7 @@ xenUnifiedNodeDeviceGetPciInfo (virNodeDevicePtr dev, + if (!xml) + goto out; + +- def = virNodeDeviceDefParseString(dev->conn, xml); ++ def = virNodeDeviceDefParseString(dev->conn, xml, EXISTING_DEVICE); + if (!def) + goto out; + +diff --git a/tests/nodedevxml2xmltest.c b/tests/nodedevxml2xmltest.c +index 29cdb9e..7621212 100644 +--- a/tests/nodedevxml2xmltest.c ++++ b/tests/nodedevxml2xmltest.c +@@ -29,7 +29,7 @@ static int testCompareXMLToXMLFiles(const char *xml) { + if (virtTestLoadFile(xml, &xmlPtr, MAX_FILE) < 0) + goto fail; + +- if (!(dev = virNodeDeviceDefParseString(NULL, xmlData))) ++ if (!(dev = virNodeDeviceDefParseString(NULL, xmlData, EXISTING_DEVICE))) + goto fail; + + if (!(actual = virNodeDeviceDefFormat(NULL, dev))) +-- +1.6.0.6 + diff --git a/docs/api_extension/0008-Step-8-of-8-Add-virsh-support.patch b/docs/api_extension/0008-Step-8-of-8-Add-virsh-support.patch new file mode 100644 index 0000000..55b758b --- /dev/null +++ b/docs/api_extension/0008-Step-8-of-8-Add-virsh-support.patch @@ -0,0 +1,133 @@ +From 193cc4abbb6c2fc5557d3699f86ff0103d5a21ef Mon Sep 17 00:00:00 2001 +From: David Allan <dallan@redhat.com> +Date: Tue, 19 May 2009 16:47:31 -0400 +Subject: [PATCH 8/8] Step 8 of 8 Add virsh support + +--- + src/virsh.c | 103 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + 1 files changed, 103 insertions(+), 0 deletions(-) + +diff --git a/src/virsh.c b/src/virsh.c +index cb32ede..ab2a2b7 100644 +--- a/src/virsh.c ++++ b/src/virsh.c +@@ -2962,6 +2962,107 @@ cmdPoolCreate(vshControl *ctl, const vshCmd *cmd) + + + /* ++ * "nodedev-create" command ++ */ ++static const vshCmdInfo info_node_device_create[] = { ++ {"help", gettext_noop("create a device defined " ++ "by an XML file on the node")}, ++ {"desc", gettext_noop("Create a device on the node. Note that this " ++ "command creates devices on the physical host " ++ "that can then be assigned to a virtual machine.")}, ++ {NULL, NULL} ++}; ++ ++static const vshCmdOptDef opts_node_device_create[] = { ++ {"file", VSH_OT_DATA, VSH_OFLAG_REQ, ++ gettext_noop("file containing an XML description of the device")}, ++ {NULL, 0, 0, NULL} ++}; ++ ++static int ++cmdNodeDeviceCreate(vshControl *ctl, const vshCmd *cmd) ++{ ++ virNodeDevicePtr dev = NULL; ++ char *from; ++ int found = 0; ++ int ret = TRUE; ++ char *buffer; ++ ++ if (!vshConnectionUsability(ctl, ctl->conn, TRUE)) ++ return FALSE; ++ ++ from = vshCommandOptString(cmd, "file", &found); ++ if (!found) { ++ return FALSE; ++ } ++ ++ if (virFileReadAll(from, VIRSH_MAX_XML_FILE, &buffer) < 0) { ++ return FALSE; ++ } ++ ++ dev = virNodeDeviceCreateXML(ctl->conn, buffer, 0); ++ free (buffer); ++ ++ if (dev != NULL) { ++ vshPrint(ctl, _("Node device %s created from %s\n"), ++ virNodeDeviceGetName(dev), from); ++ } else { ++ vshError(ctl, FALSE, _("Failed to create node device from %s"), from); ++ ret = FALSE; ++ } ++ ++ return ret; ++} ++ ++ ++/* ++ * "nodedev-destroy" command ++ */ ++static const vshCmdInfo info_node_device_destroy[] = { ++ {"help", gettext_noop("destroy a device on the node")}, ++ {"desc", gettext_noop("Destroy a device on the node. Note that this " ++ "command destroys devices on the physical host ")}, ++ {NULL, NULL} ++}; ++ ++static const vshCmdOptDef opts_node_device_destroy[] = { ++ {"name", VSH_OT_DATA, VSH_OFLAG_REQ, ++ gettext_noop("name of the device to be destroyed")}, ++ {NULL, 0, 0, NULL} ++}; ++ ++static int ++cmdNodeDeviceDestroy(vshControl *ctl, const vshCmd *cmd) ++{ ++ virNodeDevicePtr dev = NULL; ++ int ret = TRUE; ++ int found = 0; ++ char *name; ++ ++ if (!vshConnectionUsability(ctl, ctl->conn, TRUE)) { ++ return FALSE; ++ } ++ ++ name = vshCommandOptString(cmd, "name", &found); ++ if (!found) { ++ return FALSE; ++ } ++ ++ dev = virNodeDeviceLookupByName(ctl->conn, name); ++ ++ if (virNodeDeviceDestroy(dev) == 0) { ++ vshPrint(ctl, _("Destroyed node device '%s'\n"), name); ++ } else { ++ vshError(ctl, FALSE, _("Failed to destroy node device '%s'"), name); ++ ret = FALSE; ++ } ++ ++ virNodeDeviceFree(dev); ++ return ret; ++} ++ ++ ++/* + * XML Building helper for pool-define-as and pool-create-as + */ + static const vshCmdOptDef opts_pool_X_as[] = { +@@ -5895,6 +5996,8 @@ static const vshCmdDef commands[] = { + {"nodedev-dettach", cmdNodeDeviceDettach, opts_node_device_dettach, info_node_device_dettach}, + {"nodedev-reattach", cmdNodeDeviceReAttach, opts_node_device_reattach, info_node_device_reattach}, + {"nodedev-reset", cmdNodeDeviceReset, opts_node_device_reset, info_node_device_reset}, ++ {"nodedev-create", cmdNodeDeviceCreate, opts_node_device_create, info_node_device_create}, ++ {"nodedev-destroy", cmdNodeDeviceDestroy, opts_node_device_destroy, info_node_device_destroy}, + + {"pool-autostart", cmdPoolAutostart, opts_pool_autostart, info_pool_autostart}, + {"pool-build", cmdPoolBuild, opts_pool_build, info_pool_build}, +-- +1.6.0.6 + diff --git a/docs/api_extension/api_extension.html b/docs/api_extension/api_extension.html new file mode 100644 index 0000000..28250fb --- /dev/null +++ b/docs/api_extension/api_extension.html @@ -0,0 +1,264 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" +"http://www.w3.org/TR/html4/strict.dtd"> +<html> +<head> +<style type="text/css"> +h1 {text-align:center} +p {margin-left:10px} +p.filename {font-family:courier} +ol.steps li {font-size:larger;font-weight:bold} +ol.steps p {margin-left:-30px;font-size:smaller;font-weight:normal} +ol.steps p.stepname {margin-left:10px;font-weight:bold} +ol.ordinarylist li {margin-left:10px;font-size:smaller;font-weight:normal} +</style> +<title>Implementing a new API in Libvirt</title> +</head> + +<body> +<h1>Implementing a new API in Libvirt</h1> + +<p>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.</p> + +<p>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.</p> + +<p>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:</p> + +<p><a href="http://libvirt.org/downloads.html">http://libvirt.org/downloads.html</a></p> + +<p>Once you have a working development environment, the steps to create a +new API are:</p> +<ol> + <li>define the public API</li> + <li>define the internal driver API</li> + <li>implement the public API</li> + <li>define the wire protocol format</li> + <li>implement the RPC client</li> + <li>implement the server side dispatcher</li> + <li>implement the driver methods</li> + <li>add virsh support</li> +</ol> +<p>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.</p> + +<p>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.</p> + +<p>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.</p> + +<p>With that said, let's begin.</p> + +<ol class="steps"> +<li> +<p class="stepname">DEFINING THE PUBLIC API</p> + +<p>The first task is to define the public API and add it to:</p> + +<p class="filename">include/libvirt/libvirt.h.in</p> + +<p>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.</p> + +<p>Once you have defined the API, you have to add the symbol names to:</p> + +<p class="filename">src/libvirt_public.syms</p> + +<p class="example">See <a href="0001-Step-1-of-8-Define-the-public-API.patch">0001-Step-1-of-8-Define-the-public-API.patch</a> for example code.</p> +</li> +<li> +<p class="stepname">DEFINING THE INTERNAL API</p> + +<p>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.</p> + +<p>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.</p> + +<p>The driver structs are defined in:</p> + +<p class="filename">src/driver.h</p> + +<p>To define the internal API, first typedef the driver function +prototype and then add a new field for it to the relevant driver +struct.</p> + +<p class="example">See <a href="0002-Step-2-of-8-Define-the-internal-driver-API.patch">0002-Step-2-of-8-Define-the-internal-driver-API.patch</a></p> +</li> +<li> +<p class="stepname">IMPLEMENTING THE PUBLIC API</p> + +<p>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:</p> +<ol class="ordinarylist"> + <li>SHOULD log a message with VIR_DEBUG() indicating that it is + being called and its parameters;</li> + <li>MUST call virResetLastError();</li> + <li>SHOULD confirm that the connection is valid with + VIR_IS_CONNECT(conn);</li> + <li>If the API requires a connection with write privileges, SHOULD + confirm that the connection flags do not indicate that the + connection is read-only;</li> + <li>SHOULD do basic validation of the parameters that are being + passed in;</li> + <li>MUST confirm that the driver for this connection exists and that + it implements this function;</li> + <li>MUST call the internal API;</li> + <li>SHOULD log a message with VIR_DEBUG() indicating that it is + returning, its return value, and status.</li> + <li>MUST return status to the caller.</li> +</ol> + +<p>The public API calls are implemented in:</p> + +<p class="filename">src/libvirt.c</p> + +<p class="example">See <a href="0003-Step-3-of-8-Implement-the-public-API.patch">0003-Step-3-of-8-Implement-the-public-API.patch</a></p> +</li> +<li> +<p class="stepname">DEFINING THE WIRE PROTOCOL FORMAT</p> + +<p>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:</p> + +<p class="filename">qemud/remote_protocol.x</p> + +<p>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.</p> + +<p>Second, add values to the remote_procedure enum for each new function +added to the API.</p> + +<p class="example">See <a href="0004-Step-4-of-8-Define-the-wire-protocol-format.patch">0004-Step-4-of-8-Define-the-wire-protocol-format.patch</a></p> + +<p>Once these changes are in place, it's necessary to run 'make rpcgen' +in the qemud directory to create the .c and .h files required by the +remote protocol code.</p> +</li> +<li> +<p class="stepname">IMPLEMENT THE RPC CLIENT</p> + +<p>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:</p> + +<p class="filename">src/remote_internal.c</p> + +<p>Each remote method invocation does the following:</p> + +<ol class="ordinarylist"> + <li>locks the remote driver;</li> + <li>sets up the method arguments;</li> + <li>invokes the remote function;</li> + <li>checks the return value, if necessary;</li> + <li>extracts any returned data;</li> + <li>frees any returned data;</li> + <li>unlocks the remote driver.</li> +</ol> + +<p>Once you have created the remote method calls, you have to add fields +for them to the driver structs for the appropriate remote driver.</p> + +<p class="example">See <a href="0005-Step-5-of-8-Implement-the-RPC-client.patch">0005-Step-5-of-8-Implement-the-RPC-client.patch</a></p> +</li> +<li> +<p class=stepname>IMPLEMENTING THE SERVER SIDE DISPATCHER</p> + +<p>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:</p> + +<p class="filename">qemud/remote.c</p> + +<p>Again, this step uses the .h files generated by make rpcgen.</p> + +<p class="example">See <a href="0006-Step-6-of-8-Implement-the-server-side-dispatcher.patch">0006-Step-6-of-8-Implement-the-server-side-dispatcher.patch</a></p> +</li> +<li> +<p class=stepname>IMPLEMENT THE DRIVER METHODS</p> + +<p>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.</p> + +<p>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.</p> + +<p>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.</p> + +<p class="example">See <a href="0007-Step-7-of-8-Implement-the-driver-methods.patch">0007-Step-7-of-8-Implement-the-driver-methods.patch</a></p> +</li> +<li> +<p class=stepname>IMPLEMENT VIRSH SUPPORT</p> + +<p>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. </p> + +<p>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.</p> + +<p class="example">See <a href="0008-Step-8-of-8-Add-virsh-support.patch">0008-Step-8-of-8-Add-virsh-support.patch</a></p> +</li> +</ol> + +<p>Once you have working functionality, run make check and make +syntax-check before generating patches.</p> +</body> +</html> diff --git a/docs/sitemap.html.in b/docs/sitemap.html.in index 00328e1..b850a0b 100644 --- a/docs/sitemap.html.in +++ b/docs/sitemap.html.in @@ -65,6 +65,10 @@ <span>The libvirt API concepts</span> </li> <li> + <a href="api_extension/api_extension.html">Internals</a> + <span>Extending the libvirt APIs</span> + </li> + <li> <a href="archdomain.html">Domains</a> <span>Managing virtual machines</span> </li> -- 1.6.0.6