README.devel


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117


 Notes for util-linux-ng developers
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

AUTOTOOLS:

     * "./autogen.sh" generates all necessary files (run it after checkout from
       git)

     * "make distclean" removes all unnecessary files, but code is still possible
       recompile by "./configure; make"

     * "make dist-gzip" (or -bzip2) creates tarball which is possible use without
      autogen.sh


PATCHES:

     * send your patches to the mailing list or to upstream maintainer
       (see the AUTHORS file)

     * diff -u

     * don't include generated (autotools) stuff to your patches
       (hint: use git-clean [-X])

     * patches are delivered via email only.  Downloading them from internet
       servers is a pain.

     * one patch per email, with the changelog in the body of the email.

     * Subject: [PATCH] subsystem: description

     * if someone else wrote the patch, they should be credited (and blamed)
       for it. To communicate this, add a line:

          From: John Doe <jdoe@wherever.com>

     * add a Signed-off-by line (hint: use "git commit -s")

       The sign-off is a simple line at the end of the explanation for the
       patch, which certifies that you wrote it or otherwise have the right to
       pass it on as a open-source patch.  The rules are pretty simple: if you
       can certify the below:

           By making a contribution to this project, I certify that:

           (a) The contribution was created in whole or in part by me and I
               have the right to submit it under the open source license
               indicated in the file; or

           (b) The contribution is based upon previous work that, to the best
               of my knowledge, is covered under an appropriate open source
               license and I have the right under that license to submit that
               work with modifications, whether created in whole or in part
               by me, under the same open source license (unless I am
               permitted to submit under a different license), as indicated
               in the file; or

           (c) The contribution was provided directly to me by some other
               person who certified (a), (b) or (c) and I have not modified it.

           (d) I understand and agree that this project and the contribution
               are public and that a record of the contribution (including all
               personal information I submit with it, including my sign-off) is
               maintained indefinitely and may be redistributed consistent with
               this project or the open source license(s) involved.

       then you just add a line saying

               Signed-off-by: Random J Developer <random@developer.example.org>

       using your real name (sorry, no pseudonyms or anonymous contributions.)


     * for more details see:

       The perfect patch
                http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt

CODING STYLE:

     * the preferred coding style is based on the linux kernel Documentation/CodingStyle.
       For more details see:

       http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob_plain;f=Documentation/CodingStyle


SCM (source code management):

     git clone git://git.kernel.org/pub/scm/utils/util-linux-ng/util-linux-ng.git util-linux-ng


    * maintenance (stable) branch
        - created for every <major>.<minor> release
        - branch name: stable/v<major>.<minor>

    * bugfix branch
        - created for <major>.<minor>.<maint> release for critical/security bugs only
        - this branch is optional
        - branch name: stable/v<major>.<minor>.<maint>

    * master branch
        - the status of this branch is: "it works for me". It means useful
          but not well tested patches.
        - it's source for occasional snapshots
        - for long-term development or invasive changes should be an active
          development forked into a separate branch (topic branches) from the
          tip of "master".

    * A new tag object is created for:
        - every release, tag name: v<version>


    * KNOWN BUGS:
        - tag v2.13.1 is typo. Please, ignore this tag.
/*
 * String printing Visitor
 *
 * Copyright Red Hat, Inc. 2012-2016
 *
 * Author: Paolo Bonzini <pbonzini@redhat.com>
 *
 * This work is licensed under the terms of the GNU LGPL, version 2.1 or later.
 * See the COPYING.LIB file in the top-level directory.
 *
 */

#include "qemu/osdep.h"
#include "qemu-common.h"
#include "qapi/string-output-visitor.h"
#include "qapi/visitor-impl.h"
#include "qemu/host-utils.h"
#include <math.h>
#include "qemu/range.h"

enum ListMode {
    LM_NONE,             /* not traversing a list of repeated options */
    LM_STARTED,          /* next_list() ready to be called */

    LM_IN_PROGRESS,      /* next_list() has been called.
                          *
                          * Generating the next list link will consume the most
                          * recently parsed QemuOpt instance of the repeated
                          * option.
                          *
                          * Parsing a value into the list link will examine the
                          * next QemuOpt instance of the repeated option, and
                          * possibly enter LM_SIGNED_INTERVAL or
                          * LM_UNSIGNED_INTERVAL.
                          */

    LM_SIGNED_INTERVAL,  /* next_list() has been called.
                          *
                          * Generating the next list link will consume the most
                          * recently stored element from the signed interval,
                          * parsed from the most recent QemuOpt instance of the
                          * repeated option. This may consume QemuOpt itself
                          * and return to LM_IN_PROGRESS.
                          *
                          * Parsing a value into the list link will store the
                          * next element of the signed interval.
                          */

    LM_UNSIGNED_INTERVAL,/* Same as above, only for an unsigned interval. */

    LM_END,              /* next_list() called, about to see last element. */
};

typedef enum ListMode ListMode;

struct StringOutputVisitor
{
    Visitor visitor;
    bool human;
    GString *string;
    char **result;
    ListMode list_mode;
    union {
        int64_t s;
        uint64_t u;
    } range_start, range_end;
    GList *ranges;
    void *list; /* Only needed for sanity checking the caller */
};

static StringOutputVisitor *to_sov(Visitor *v)
{
    return container_of(v, StringOutputVisitor, visitor);
}

static void string_output_set(StringOutputVisitor *sov, char *string)
{
    if (sov->string) {
        g_string_free(sov->string, true);
    }
    sov->string = g_string_new(string);
    g_free(string);
}

static void string_output_append(StringOutputVisitor *sov, int64_t a)
{
    Range *r = g_malloc0(sizeof(*r));

    range_set_bounds(r, a, a);
    sov->ranges = range_list_insert(sov->ranges, r);
}

static void string_output_append_range(StringOutputVisitor *sov,
                                       int64_t s, int64_t e)
{
    Range *r = g_malloc0(sizeof(*r));

    range_set_bounds(r, s, e);
    sov->ranges = range_list_insert(sov->ranges, r);
}

static void format_string(StringOutputVisitor *sov, Range *r, bool next,
                          bool human)
{
    if (range_lob(r) != range_upb(r)) {
        if (human) {
            g_string_append_printf(sov->string, "0x%" PRIx64 "-0x%" PRIx64,
                                   range_lob(r), range_upb(r));

        } else {
            g_string_append_printf(sov->string, "%" PRId64 "-%" PRId64,
                                   range_lob(r), range_upb(r));
        }
    } else {
        if (human) {
            g_string_append_printf(sov->string, "0x%" PRIx64, range_lob(r));
        } else {
            g_string_append_printf(sov->string, "%" PRId64, range_lob(r));
        }
    }
    if (next) {
        g_string_append(sov->string, ",");
    }
}

static void print_type_int64(Visitor *v, const char *name, int64_t *obj,
                             Error **errp)
{
    StringOutputVisitor *sov = to_sov(v);
    GList *l;

    switch (sov->list_mode) {
    case LM_NONE:
        string_output_append(sov, *obj);
        break;

    case LM_STARTED:
        sov->range_start.s = *obj;
        sov->range_end.s = *obj;
        sov->list_mode = LM_IN_PROGRESS;
        return;

    case LM_IN_PROGRESS:
        if (sov->range_end.s + 1 == *obj) {
            sov->range_end.s++;
        } else {
            if (sov->range_start.s == sov->range_end.s) {
                string_output_append(sov, sov->range_end.s);
            } else {
                assert(sov->range_start.s < sov->range_end.s);
                string_output_append_range(sov, sov->range_start.s,
                                           sov->range_end.s);
            }

            sov->range_start.s = *obj;
            sov->range_end.s = *obj;
        }
        return;

    case LM_END:
        if (sov->range_end.s + 1 == *obj) {
            sov->range_end.s++;
            assert(sov->range_start.s < sov->range_end.s);
            string_output_append_range(sov, sov->range_start.s,
                                       sov->range_end.s);
        } else {
            if (sov->range_start.s == sov->range_end.s) {
                string_output_append(sov, sov->range_end.s);
            } else {
                assert(sov->range_start.s < sov->range_end.s);

                string_output_append_range(sov, sov->range_start.s,
                                           sov->range_end.s);
            }
            string_output_append(sov, *obj);
        }
        break;

    default:
        abort();
    }

    l = sov->ranges;
    while (l) {
        Range *r = l->data;
        format_string(sov, r, l->next != NULL, false);
        l = l->next;
    }

    if (sov->human) {
        l = sov->ranges;
        g_string_append(sov->string, " (");
        while (l) {
            Range *r = l->data;
            format_string(sov, r, l->next != NULL, true);
            l = l->next;
        }
        g_string_append(sov->string, ")");
    }
}

static void print_type_uint64(Visitor *v, const char *name, uint64_t *obj,
                             Error **errp)
{
    /* FIXME: print_type_int64 mishandles values over INT64_MAX */
    int64_t i = *obj;
    print_type_int64(v, name, &i, errp);
}

static void print_type_size(Visitor *v, const char *name, uint64_t *obj,
                            Error **errp)
{
    StringOutputVisitor *sov = to_sov(v);
    uint64_t val;
    char *out, *psize;

    if (!sov->human) {
        out = g_strdup_printf("%"PRIu64, *obj);
        string_output_set(sov, out);
        return;
    }

    val = *obj;
    psize = size_to_str(val);
    out = g_strdup_printf("%"PRIu64" (%s)", val, psize);
    string_output_set(sov, out);

    g_free(psize);
}

static void print_type_bool(Visitor *v, const char *name, bool *obj,
                            Error **errp)
{
    StringOutputVisitor *sov = to_sov(v);
    string_output_set(sov, g_strdup(*obj ? "true" : "false"));
}

static void print_type_str(Visitor *v, const char *name, char **obj,
                           Error **errp)
{
    StringOutputVisitor *sov = to_sov(v);
    char *out;

    if (sov->human) {
        out = *obj ? g_strdup_printf("\"%s\"", *obj) : g_strdup("<null>");
    } else {
        out = g_strdup(*obj ? *obj : "");
    }
    string_output_set(sov, out);
}

static void print_type_number(Visitor *v, const char *name, double *obj,
                              Error **errp)
{
    StringOutputVisitor *sov = to_sov(v);
    string_output_set(sov, g_strdup_printf("%f", *obj));
}

static void print_type_null(Visitor *v, const char *name, QNull **obj,
                            Error **errp)
{
    StringOutputVisitor *sov = to_sov(v);
    char *out;

    if (sov->human) {
        out = g_strdup("<null>");
    } else {
        out = g_strdup("");
    }
    string_output_set(sov, out);
}

static void
start_list(Visitor *v, const char *name, GenericList **list, size_t size,
           Error **errp)
{
    StringOutputVisitor *sov = to_sov(v);

    /* we can't traverse a list in a list */
    assert(sov->list_mode == LM_NONE);
    /* We don't support visits without a list */
    assert(list);
    sov->list = list;
    /* List handling is only needed if there are at least two elements */
    if (*list && (*list)->next) {
        sov->list_mode = LM_STARTED;
    }
}

static GenericList *next_list(Visitor *v, GenericList *tail, size_t size)
{
    StringOutputVisitor *sov = to_sov(v);
    GenericList *ret = tail->next;

    if (ret && !ret->next) {
        sov->list_mode = LM_END;
    }
    return ret;
}

static void end_list(Visitor *v, void **obj)
{
    StringOutputVisitor *sov = to_sov(v);

    assert(sov->list == obj);
    assert(sov->list_mode == LM_STARTED ||
           sov->list_mode == LM_END ||
           sov->list_mode == LM_NONE ||
           sov->list_mode == LM_IN_PROGRESS);
    sov->list_mode = LM_NONE;
}

static void string_output_complete(Visitor *v, void *opaque)
{
    StringOutputVisitor *sov = to_sov(v);

    assert(opaque == sov->result);
    *sov->result = g_string_free(sov->string, false);
    sov->string = NULL;
}

static void free_range(void *range, void *dummy)
{
    g_free(range);
}

static void string_output_free(Visitor *v)
{
    StringOutputVisitor *sov = to_sov(v);

    if (sov->string) {
        g_string_free(sov->string, true);
    }

    g_list_foreach(sov->ranges, free_range, NULL);
    g_list_free(sov->ranges);
    g_free(sov);
}

Visitor *string_output_visitor_new(bool human, char **result)
{
    StringOutputVisitor *v;

    v = g_malloc0(sizeof(*v));

    v->string = g_string_new(NULL);
    v->human = human;
    v->result = result;
    *result = NULL;

    v->visitor.type = VISITOR_OUTPUT;
    v->visitor.type_int64 = print_type_int64;
    v->visitor.type_uint64 = print_type_uint64;
    v->visitor.type_size = print_type_size;
    v->visitor.type_bool = print_type_bool;
    v->visitor.type_str = print_type_str;
    v->visitor.type_number = print_type_number;
    v->visitor.type_null = print_type_null;
    v->visitor.start_list = start_list;
    v->visitor.next_list = next_list;
    v->visitor.end_list = end_list;
    v->visitor.complete = string_output_complete;
    v->visitor.free = string_output_free;

    return &v->visitor;
}