qemu

FORK: QEMU emulator
git clone https://git.neptards.moe/neptards/qemu.git
Log | Files | Refs | Submodules | LICENSE

visitor-impl.h (4541B)

      1 /*
      2  * Core Definitions for QAPI Visitor implementations
      3  *
      4  * Copyright (C) 2012-2016 Red Hat, Inc.
      5  *
      6  * Author: Paolo Bonizni <pbonzini@redhat.com>
      7  *
      8  * This work is licensed under the terms of the GNU LGPL, version 2.1 or later.
      9  * See the COPYING.LIB file in the top-level directory.
     10  *
     11  */
     12 #ifndef QAPI_VISITOR_IMPL_H
     13 #define QAPI_VISITOR_IMPL_H
     14 
     15 #include "qapi/visitor.h"
     16 
     17 /*
     18  * This file describes the callback interface for implementing a QAPI
     19  * visitor.  For the client interface, see visitor.h.  When
     20  * implementing the callbacks, it is easiest to declare a struct with
     21  * 'Visitor visitor;' as the first member.  A callback's contract
     22  * matches the corresponding public functions' contract unless stated
     23  * otherwise.  In the comments below, some callbacks are marked "must
     24  * be set for $TYPE visits to work"; if a visitor implementation omits
     25  * that callback, it should also document that it is only useful for a
     26  * subset of QAPI.
     27  */
     28 
     29 /*
     30  * There are four classes of visitors; setting the class determines
     31  * how QAPI enums are visited, as well as what additional restrictions
     32  * can be asserted.  The values are intentionally chosen so as to
     33  * permit some assertions based on whether a given bit is set (that
     34  * is, some assertions apply to input and clone visitors, some
     35  * assertions apply to output and clone visitors).
     36  */
     37 typedef enum VisitorType {
     38     VISITOR_INPUT = 1,
     39     VISITOR_OUTPUT = 2,
     40     VISITOR_CLONE = 3,
     41     VISITOR_DEALLOC = 4,
     42 } VisitorType;
     43 
     44 struct Visitor
     45 {
     46     /*
     47      * Only input visitors may fail!
     48      */
     49 
     50     /* Must be set to visit structs */
     51     bool (*start_struct)(Visitor *v, const char *name, void **obj,
     52                          size_t size, Error **errp);
     53 
     54     /* Optional; intended for input visitors */
     55     bool (*check_struct)(Visitor *v, Error **errp);
     56 
     57     /* Must be set to visit structs */
     58     void (*end_struct)(Visitor *v, void **obj);
     59 
     60     /* Must be set; implementations may require @list to be non-null,
     61      * but must document it. */
     62     bool (*start_list)(Visitor *v, const char *name, GenericList **list,
     63                        size_t size, Error **errp);
     64 
     65     /* Must be set */
     66     GenericList *(*next_list)(Visitor *v, GenericList *tail, size_t size);
     67 
     68     /* Optional; intended for input visitors */
     69     bool (*check_list)(Visitor *v, Error **errp);
     70 
     71     /* Must be set */
     72     void (*end_list)(Visitor *v, void **list);
     73 
     74     /* Must be set by input and clone visitors to visit alternates */
     75     bool (*start_alternate)(Visitor *v, const char *name,
     76                             GenericAlternate **obj, size_t size,
     77                             Error **errp);
     78 
     79     /* Optional */
     80     void (*end_alternate)(Visitor *v, void **obj);
     81 
     82     /* Must be set */
     83     bool (*type_int64)(Visitor *v, const char *name, int64_t *obj,
     84                        Error **errp);
     85 
     86     /* Must be set */
     87     bool (*type_uint64)(Visitor *v, const char *name, uint64_t *obj,
     88                         Error **errp);
     89 
     90     /* Optional; fallback is type_uint64() */
     91     bool (*type_size)(Visitor *v, const char *name, uint64_t *obj,
     92                       Error **errp);
     93 
     94     /* Must be set */
     95     bool (*type_bool)(Visitor *v, const char *name, bool *obj, Error **errp);
     96 
     97     /* Must be set */
     98     bool (*type_str)(Visitor *v, const char *name, char **obj, Error **errp);
     99 
    100     /* Must be set to visit numbers */
    101     bool (*type_number)(Visitor *v, const char *name, double *obj,
    102                         Error **errp);
    103 
    104     /* Must be set to visit arbitrary QTypes */
    105     bool (*type_any)(Visitor *v, const char *name, QObject **obj,
    106                      Error **errp);
    107 
    108     /* Must be set to visit explicit null values.  */
    109     bool (*type_null)(Visitor *v, const char *name, QNull **obj,
    110                       Error **errp);
    111 
    112     /* Must be set for input visitors to visit structs, optional otherwise.
    113        The core takes care of the return type in the public interface. */
    114     void (*optional)(Visitor *v, const char *name, bool *present);
    115 
    116     /* Optional */
    117     bool (*policy_reject)(Visitor *v, const char *name,
    118                           unsigned special_features, Error **errp);
    119 
    120     /* Optional */
    121     bool (*policy_skip)(Visitor *v, const char *name,
    122                         unsigned special_features);
    123 
    124     /* Must be set */
    125     VisitorType type;
    126 
    127     /* Optional */
    128     struct CompatPolicy compat_policy;
    129 
    130     /* Must be set for output visitors, optional otherwise. */
    131     void (*complete)(Visitor *v, void *opaque);
    132 
    133     /* Must be set */
    134     void (*free)(Visitor *v);
    135 };
    136 
    137 #endif