xref: /openbmc/qemu/include/qapi/visitor-impl.h (revision 764a6ee9)
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
138