debuggers.hg

changeset 21190:5d96ac36d97e

libxl: Per-domain data storage for the convenience of the library user

We provide a mechanism whereby a user of the libxl library is able to
store some information alongside the domain. The information stored
is a block of bytes. Its lifetime is that of the domain - ie the
userdata is garbage collected alongside the domain if the domain is
destroyed. (This is why the feature needs to be in libxl and cannot
be implemented in the user itself or in libxlutil.)

If a libxl caller does not need to use this feature it can ignore it.

The data is tagged with the (self-declared) name of the libxl user, so
that different users cannot accidentally trip over each others'
userdata. The data is not interpreted at all by libxl.

To assist developers and people debugging, there is a registry of the
known userdata userids, and the corresponding data format as declared
by that libxl user, in libxl.h next to these declarations:

int libxl_userdata_store(struct libxl_ctx *ctx, uint32_t domid,
const char *userdata_userid,
const uint8_t *data, int datalen);
int libxl_userdata_retrieve(struct libxl_ctx *ctx, uint32_t domid,
const char *userdata_userid,
uint8_t **data_r, int *datalen_r);

The next patch will introduce the data for the userid "xl".

Signed-off-by: Ian Jackson <Ian.Jackson@eu.citrix.com>
author Keir Fraser <keir.fraser@citrix.com>
date Mon Apr 12 17:44:01 2010 +0100 (2010-04-12)
parents fd0fd3612eb8
children be6e58cc2475
files tools/libxl/libxl.c tools/libxl/libxl.h tools/libxl/libxl_dom.c tools/libxl/libxl_internal.h
line diff
     1.1 --- a/tools/libxl/libxl.c	Mon Apr 12 17:43:25 2010 +0100
     1.2 +++ b/tools/libxl/libxl.c	Mon Apr 12 17:44:01 2010 +0100
     1.3 @@ -725,6 +725,8 @@ int libxl_domain_destroy(struct libxl_ct
     1.4          if (!xs_rm(ctx->xsh, XBT_NULL, xapi_path))
     1.5              XL_LOG_ERRNO(ctx, XL_LOG_ERROR, "xs_rm failed for %s", xapi_path);
     1.6  
     1.7 +    libxl__userdata_destroyall(ctx, domid);
     1.8 +
     1.9      rc = xc_domain_destroy(ctx->xch, domid);
    1.10      if (rc < 0) {
    1.11          XL_LOG_ERRNOVAL(ctx, XL_LOG_ERROR, rc, "xc_domain_destroy failed for %d", domid);
     2.1 --- a/tools/libxl/libxl.h	Mon Apr 12 17:43:25 2010 +0100
     2.2 +++ b/tools/libxl/libxl.h	Mon Apr 12 17:44:01 2010 +0100
     2.3 @@ -366,6 +366,37 @@ int libxl_device_pci_init(libxl_device_p
     2.4                            unsigned int bus, unsigned int dev,
     2.5                            unsigned int func, unsigned int vdevfn);
     2.6  
     2.7 +/*
     2.8 + * Functions for allowing users of libxl to store private data
     2.9 + * relating to a domain.  The data is an opaque sequence of bytes and
    2.10 + * is not interpreted or used by libxl.
    2.11 + *
    2.12 + * Data is indexed by the userdata userid, which is a short printable
    2.13 + * ASCII string.  The following list is a registry of userdata userids
    2.14 + * (the registry may be updated by posting a patch to xen-devel):
    2.15 + *
    2.16 + *  userid      Data contents
    2.17 + *   "xl"        domain config file in xl format, Unix line endings
    2.18 + *
    2.19 + * libxl does not enforce the registration of userdata userids or the
    2.20 + * semantics of the data.  For specifications of the data formats
    2.21 + * see the code or documentation for the libxl caller in question.
    2.22 + */
    2.23 +int libxl_userdata_store(struct libxl_ctx *ctx, uint32_t domid,
    2.24 +                              const char *userdata_userid,
    2.25 +                              const uint8_t *data, int datalen);
    2.26 +  /* If datalen==0, data is not used and the user data for
    2.27 +   * that domain and userdata_userid is deleted. */
    2.28 +int libxl_userdata_retrieve(struct libxl_ctx *ctx, uint32_t domid,
    2.29 +                                 const char *userdata_userid,
    2.30 +                                 uint8_t **data_r, int *datalen_r);
    2.31 +  /* On successful return, *data_r is from malloc.
    2.32 +   * If there is no data for that domain and userdata_userid,
    2.33 +   * *data_r and *datalen_r will be set to 0.
    2.34 +   * data_r and datalen_r may be 0.
    2.35 +   * On error return, *data_r and *datalen_r are undefined.
    2.36 +   */
    2.37 +
    2.38  typedef enum {
    2.39      POWER_BUTTON,
    2.40      SLEEP_BUTTON
     3.1 --- a/tools/libxl/libxl_dom.c	Mon Apr 12 17:43:25 2010 +0100
     3.2 +++ b/tools/libxl/libxl_dom.c	Mon Apr 12 17:44:01 2010 +0100
     3.3 @@ -16,6 +16,8 @@
     3.4  #include "libxl_osdeps.h"
     3.5  
     3.6  #include <stdio.h>
     3.7 +#include <assert.h>
     3.8 +#include <glob.h>
     3.9  #include <inttypes.h>
    3.10  #include <string.h>
    3.11  #include <sys/time.h> /* for struct timeval */
    3.12 @@ -356,3 +358,128 @@ char *libxl_uuid2string(struct libxl_ctx
    3.13      if (!s) XL_LOG(ctx, XL_LOG_ERROR, "cannot allocate for uuid");
    3.14      return s;
    3.15  }
    3.16 +
    3.17 +static const char *userdata_path(struct libxl_ctx *ctx, uint32_t domid,
    3.18 +                                      const char *userdata_userid,
    3.19 +                                      const char *wh) {
    3.20 +    char *path, *uuid_string;
    3.21 +    struct libxl_dominfo info;
    3.22 +    int rc;
    3.23 +
    3.24 +    rc = libxl_domain_info(ctx, &info, domid);
    3.25 +    if (rc) {
    3.26 +        XL_LOG_ERRNO(ctx, XL_LOG_ERROR, "unable to find domain info"
    3.27 +                     " for domain %l"PRIu32, domid);
    3.28 +        return 0;
    3.29 +    }
    3.30 +    uuid_string = string_of_uuid(ctx, info.uuid);
    3.31 +
    3.32 +    path = libxl_sprintf(ctx, "/var/lib/xen/"
    3.33 +                         "userdata-%s.%s.%s",
    3.34 +                         wh, uuid_string, userdata_userid);
    3.35 +    if (!path)
    3.36 +        XL_LOG_ERRNO(ctx, XL_LOG_ERROR, "unable to allocate for"
    3.37 +                     " userdata path");
    3.38 +    return path;
    3.39 +}
    3.40 +
    3.41 +static int userdata_delete(struct libxl_ctx *ctx, const char *path) {
    3.42 +    int r;
    3.43 +    r = unlink(path);
    3.44 +    if (r) {
    3.45 +        XL_LOG_ERRNO(ctx, XL_LOG_ERROR, "remove failed for %s", path);
    3.46 +        return errno;
    3.47 +    }
    3.48 +    return 0;
    3.49 +}
    3.50 +
    3.51 +void libxl__userdata_destroyall(struct libxl_ctx *ctx, uint32_t domid) {
    3.52 +    const char *pattern;
    3.53 +    glob_t gl;
    3.54 +    int r, i;
    3.55 +
    3.56 +    pattern = userdata_path(ctx, domid, "*", "?");
    3.57 +    if (!pattern) return;
    3.58 +
    3.59 +    gl.gl_pathc = 0;
    3.60 +    gl.gl_pathv = 0;
    3.61 +    gl.gl_offs = 0;
    3.62 +    r = glob(pattern, GLOB_ERR|GLOB_NOSORT|GLOB_MARK, 0, &gl);
    3.63 +    if (r == GLOB_NOMATCH) return;
    3.64 +    if (r) XL_LOG_ERRNO(ctx, XL_LOG_ERROR, "glob failed for %s", pattern);
    3.65 +
    3.66 +    for (i=0; i<gl.gl_pathc; i++) {
    3.67 +        userdata_delete(ctx, gl.gl_pathv[i]);
    3.68 +    }
    3.69 +    globfree(&gl);
    3.70 +}
    3.71 +
    3.72 +int libxl_userdata_store(struct libxl_ctx *ctx, uint32_t domid,
    3.73 +                              const char *userdata_userid,
    3.74 +                              const uint8_t *data, int datalen) {
    3.75 +    const char *filename;
    3.76 +    const char *newfilename;
    3.77 +    int e;
    3.78 +    int fd = -1;
    3.79 +    FILE *f = 0;
    3.80 +    size_t rs;
    3.81 +
    3.82 +    filename = userdata_path(ctx, domid, userdata_userid, "d");
    3.83 +    if (!filename) return ENOMEM;
    3.84 +
    3.85 +    if (!datalen)
    3.86 +        return userdata_delete(ctx, filename);
    3.87 +
    3.88 +    newfilename = userdata_path(ctx, domid, userdata_userid, "n");
    3.89 +    if (!newfilename) return ENOMEM;
    3.90 +
    3.91 +    fd= open(newfilename, O_RDWR|O_CREAT|O_TRUNC, 0600);
    3.92 +    if (fd<0) goto xe;
    3.93 +
    3.94 +    f= fdopen(fd, "wb");
    3.95 +    if (!f) goto xe;
    3.96 +    fd = -1;
    3.97 +
    3.98 +    rs = fwrite(data, 1, datalen, f);
    3.99 +    if (rs != datalen) { assert(ferror(f)); goto xe; }
   3.100 +
   3.101 +    if (fclose(f)) goto xe;
   3.102 +    f = 0;
   3.103 +
   3.104 +    if (rename(newfilename,filename)) goto xe;
   3.105 +
   3.106 +    return 0;
   3.107 +
   3.108 + xe:
   3.109 +    e = errno;
   3.110 +    if (f) fclose(f);
   3.111 +    if (fd>=0) close(fd);
   3.112 +
   3.113 +    XL_LOG_ERRNO(ctx, XL_LOG_ERROR, "cannot write %s for %s",
   3.114 +                 newfilename, filename);
   3.115 +    return e;
   3.116 +}
   3.117 +
   3.118 +int libxl_userdata_retrieve(struct libxl_ctx *ctx, uint32_t domid,
   3.119 +                                 const char *userdata_userid,
   3.120 +                                 uint8_t **data_r, int *datalen_r) {
   3.121 +    const char *filename;
   3.122 +    int e;
   3.123 +    int datalen = 0;
   3.124 +    void *data = 0;
   3.125 +
   3.126 +    filename = userdata_path(ctx, domid, userdata_userid, "d");
   3.127 +    if (!filename) return ENOMEM;
   3.128 +
   3.129 +    e = libxl_read_file_contents(ctx, filename, data_r ? &data : 0, &datalen);
   3.130 +
   3.131 +    if (!e && !datalen) {
   3.132 +        XL_LOG(ctx, XL_LOG_ERROR, "userdata file %s is empty", filename);
   3.133 +        if (data_r) assert(!*data_r);
   3.134 +        return EPROTO;
   3.135 +    }
   3.136 +
   3.137 +    if (data_r) *data_r = data;
   3.138 +    if (datalen_r) *datalen_r = datalen;
   3.139 +    return 0;
   3.140 +}
     4.1 --- a/tools/libxl/libxl_internal.h	Mon Apr 12 17:43:25 2010 +0100
     4.2 +++ b/tools/libxl/libxl_internal.h	Mon Apr 12 17:44:01 2010 +0100
     4.3 @@ -130,6 +130,7 @@ int restore_common(struct libxl_ctx *ctx
     4.4                     libxl_domain_build_info *info, libxl_domain_build_state *state, int fd);
     4.5  int core_suspend(struct libxl_ctx *ctx, uint32_t domid, int fd, int hvm, int live, int debug);
     4.6  int save_device_model(struct libxl_ctx *ctx, uint32_t domid, int fd);
     4.7 +void libxl__userdata_destroyall(struct libxl_ctx *ctx, uint32_t domid);
     4.8  
     4.9  /* from xl_device */
    4.10  char *device_disk_backend_type_of_phystype(libxl_disk_phystype phystype);