Merge remote-tracking branch 'remotes/rth/tags/pull-atomic-20161026' into staging
[qemu/ar7.git] / include / qapi / visitor.h
blob9bb6cba237cbe00426680119a9340a018346288b
1 /*
2 * Core Definitions for QAPI Visitor Classes
4 * Copyright (C) 2012-2016 Red Hat, Inc.
5 * Copyright IBM, Corp. 2011
7 * Authors:
8 * Anthony Liguori <aliguori@us.ibm.com>
10 * This work is licensed under the terms of the GNU LGPL, version 2.1 or later.
11 * See the COPYING.LIB file in the top-level directory.
15 #ifndef QAPI_VISITOR_H
16 #define QAPI_VISITOR_H
18 #include "qapi/qmp/qobject.h"
21 * The QAPI schema defines both a set of C data types, and a QMP wire
22 * format. QAPI objects can contain references to other QAPI objects,
23 * resulting in a directed acyclic graph. QAPI also generates visitor
24 * functions to walk these graphs. This file represents the interface
25 * for doing work at each node of a QAPI graph; it can also be used
26 * for a virtual walk, where there is no actual QAPI C struct.
28 * There are four kinds of visitor classes: input visitors (QObject,
29 * string, and QemuOpts) parse an external representation and build
30 * the corresponding QAPI graph, output visitors (QObject and string) take
31 * a completed QAPI graph and generate an external representation, the
32 * dealloc visitor can take a QAPI graph (possibly partially
33 * constructed) and recursively free its resources, and the clone
34 * visitor performs a deep clone of one QAPI object to another. While
35 * the dealloc and QObject input/output visitors are general, the string,
36 * QemuOpts, and clone visitors have some implementation limitations;
37 * see the documentation for each visitor for more details on what it
38 * supports. Also, see visitor-impl.h for the callback contracts
39 * implemented by each visitor, and docs/qapi-code-gen.txt for more
40 * about the QAPI code generator.
42 * All of the visitors are created via:
44 * Visitor *subtype_visitor_new(parameters...);
46 * A visitor should be used for exactly one top-level visit_type_FOO()
47 * or virtual walk; if that is successful, the caller can optionally
48 * call visit_complete() (for now, useful only for output visits, but
49 * safe to call on all visits). Then, regardless of success or
50 * failure, the user should call visit_free() to clean up resources.
51 * It is okay to free the visitor without completing the visit, if
52 * some other error is detected in the meantime.
54 * All QAPI types have a corresponding function with a signature
55 * roughly compatible with this:
57 * void visit_type_FOO(Visitor *v, const char *name, T obj, Error **errp);
59 * where T is FOO for scalar types, and FOO * otherwise. The scalar
60 * visitors are declared here; the remaining visitors are generated in
61 * qapi-visit.h.
63 * The @name parameter of visit_type_FOO() describes the relation
64 * between this QAPI value and its parent container. When visiting
65 * the root of a tree, @name is ignored; when visiting a member of an
66 * object, @name is the key associated with the value; and when
67 * visiting a member of a list, @name is NULL.
69 * FIXME: Clients must pass NULL for @name when visiting a member of a
70 * list, but this leads to poor error messages; it might be nicer to
71 * require a non-NULL name such as "key.0" for '{ "key": [ "value" ]
72 * }' if an error is encountered on "value" (or to have the visitor
73 * core auto-generate the nicer name).
75 * The visit_type_FOO() functions expect a non-null @obj argument;
76 * they allocate *@obj during input visits, leave it unchanged on
77 * output visits, and recursively free any resources during a dealloc
78 * visit. Each function also takes the customary @errp argument (see
79 * qapi/error.h for details), for reporting any errors (such as if a
80 * member @name is not present, or is present but not the specified
81 * type).
83 * If an error is detected during visit_type_FOO() with an input
84 * visitor, then *@obj will be NULL for pointer types, and left
85 * unchanged for scalar types. Using an output or clone visitor with
86 * an incomplete object has undefined behavior (other than a special
87 * case for visit_type_str() treating NULL like ""), while the dealloc
88 * visitor safely handles incomplete objects. Since input visitors
89 * never produce an incomplete object, such an object is possible only
90 * by manual construction.
92 * For the QAPI object types (structs, unions, and alternates), there
93 * is an additional generated function in qapi-visit.h compatible
94 * with:
96 * void visit_type_FOO_members(Visitor *v, FOO *obj, Error **errp);
98 * for visiting the members of a type without also allocating the QAPI
99 * struct.
101 * Additionally, in qapi-types.h, all QAPI pointer types (structs,
102 * unions, alternates, and lists) have a generated function compatible
103 * with:
105 * void qapi_free_FOO(FOO *obj);
107 * where behaves like free() in that @obj may be NULL. Such objects
108 * may also be used with the following macro, provided alongside the
109 * clone visitor:
111 * Type *QAPI_CLONE(Type, src);
113 * in order to perform a deep clone of @src. Because of the generated
114 * qapi_free functions and the QAPI_CLONE() macro, the clone and
115 * dealloc visitor should not be used directly outside of QAPI code.
117 * QAPI types can also inherit from a base class; when this happens, a
118 * function is generated for easily going from the derived type to the
119 * base type:
121 * BASE *qapi_CHILD_base(CHILD *obj);
123 * For a real QAPI struct, typical input usage involves:
125 * <example>
126 * Foo *f;
127 * Error *err = NULL;
128 * Visitor *v;
130 * v = FOO_visitor_new(...);
131 * visit_type_Foo(v, NULL, &f, &err);
132 * if (err) {
133 * ...handle error...
134 * } else {
135 * ...use f...
137 * visit_free(v);
138 * qapi_free_Foo(f);
139 * </example>
141 * For a list, it is:
142 * <example>
143 * FooList *l;
144 * Error *err = NULL;
145 * Visitor *v;
147 * v = FOO_visitor_new(...);
148 * visit_type_FooList(v, NULL, &l, &err);
149 * if (err) {
150 * ...handle error...
151 * } else {
152 * for ( ; l; l = l->next) {
153 * ...use l->value...
156 * visit_free(v);
157 * qapi_free_FooList(l);
158 * </example>
160 * Similarly, typical output usage is:
162 * <example>
163 * Foo *f = ...obtain populated object...
164 * Error *err = NULL;
165 * Visitor *v;
166 * Type *result;
168 * v = FOO_visitor_new(..., &result);
169 * visit_type_Foo(v, NULL, &f, &err);
170 * if (err) {
171 * ...handle error...
172 * } else {
173 * visit_complete(v, &result);
174 * ...use result...
176 * visit_free(v);
177 * </example>
179 * When visiting a real QAPI struct, this file provides several
180 * helpers that rely on in-tree information to control the walk:
181 * visit_optional() for the 'has_member' field associated with
182 * optional 'member' in the C struct; and visit_next_list() for
183 * advancing through a FooList linked list. Similarly, the
184 * visit_is_input() helper makes it possible to write code that is
185 * visitor-agnostic everywhere except for cleanup. Only the generated
186 * visit_type functions need to use these helpers.
188 * It is also possible to use the visitors to do a virtual walk, where
189 * no actual QAPI struct is present. In this situation, decisions
190 * about what needs to be walked are made by the calling code, and
191 * structured visits are split between pairs of start and end methods
192 * (where the end method must be called if the start function
193 * succeeded, even if an intermediate visit encounters an error).
194 * Thus, a virtual walk corresponding to '{ "list": [1, 2] }' looks
195 * like:
197 * <example>
198 * Visitor *v;
199 * Error *err = NULL;
200 * int value;
202 * v = FOO_visitor_new(...);
203 * visit_start_struct(v, NULL, NULL, 0, &err);
204 * if (err) {
205 * goto out;
207 * visit_start_list(v, "list", NULL, 0, &err);
208 * if (err) {
209 * goto outobj;
211 * value = 1;
212 * visit_type_int(v, NULL, &value, &err);
213 * if (err) {
214 * goto outlist;
216 * value = 2;
217 * visit_type_int(v, NULL, &value, &err);
218 * if (err) {
219 * goto outlist;
221 * outlist:
222 * visit_end_list(v, NULL);
223 * if (!err) {
224 * visit_check_struct(v, &err);
226 * outobj:
227 * visit_end_struct(v, NULL);
228 * out:
229 * error_propagate(errp, err);
230 * visit_free(v);
231 * </example>
234 /*** Useful types ***/
236 /* This struct is layout-compatible with all other *List structs
237 * created by the QAPI generator. It is used as a typical
238 * singly-linked list. */
239 typedef struct GenericList {
240 struct GenericList *next;
241 char padding[];
242 } GenericList;
244 /* This struct is layout-compatible with all Alternate types
245 * created by the QAPI generator. */
246 typedef struct GenericAlternate {
247 QType type;
248 char padding[];
249 } GenericAlternate;
251 /*** Visitor cleanup ***/
254 * Complete the visit, collecting any output.
256 * May only be called only once after a successful top-level
257 * visit_type_FOO() or visit_end_ITEM(), and marks the end of the
258 * visit. The @opaque pointer should match the output parameter
259 * passed to the subtype_visitor_new() used to create an output
260 * visitor, or NULL for any other visitor. Needed for output
261 * visitors, but may also be called with other visitors.
263 void visit_complete(Visitor *v, void *opaque);
266 * Free @v and any resources it has tied up.
268 * May be called whether or not the visit has been successfully
269 * completed, but should not be called until a top-level
270 * visit_type_FOO() or visit_start_ITEM() has been performed on the
271 * visitor. Safe if @v is NULL.
273 void visit_free(Visitor *v);
276 /*** Visiting structures ***/
279 * Start visiting an object @obj (struct or union).
281 * @name expresses the relationship of this object to its parent
282 * container; see the general description of @name above.
284 * @obj must be non-NULL for a real walk, in which case @size
285 * determines how much memory an input or clone visitor will allocate
286 * into *@obj. @obj may also be NULL for a virtual walk, in which
287 * case @size is ignored.
289 * @errp obeys typical error usage, and reports failures such as a
290 * member @name is not present, or present but not an object. On
291 * error, input visitors set *@obj to NULL.
293 * After visit_start_struct() succeeds, the caller may visit its
294 * members one after the other, passing the member's name and address
295 * within the struct. Finally, visit_end_struct() needs to be called
296 * with the same @obj to clean up, even if intermediate visits fail.
297 * See the examples above.
299 * FIXME Should this be named visit_start_object, since it is also
300 * used for QAPI unions, and maps to JSON objects?
302 void visit_start_struct(Visitor *v, const char *name, void **obj,
303 size_t size, Error **errp);
306 * Prepare for completing an object visit.
308 * @errp obeys typical error usage, and reports failures such as
309 * unparsed keys remaining in the input stream.
311 * Should be called prior to visit_end_struct() if all other
312 * intermediate visit steps were successful, to allow the visitor one
313 * last chance to report errors. May be skipped on a cleanup path,
314 * where there is no need to check for further errors.
316 void visit_check_struct(Visitor *v, Error **errp);
319 * Complete an object visit started earlier.
321 * @obj must match what was passed to the paired visit_start_struct().
323 * Must be called after any successful use of visit_start_struct(),
324 * even if intermediate processing was skipped due to errors, to allow
325 * the backend to release any resources. Destroying the visitor early
326 * with visit_free() behaves as if this was implicitly called.
328 void visit_end_struct(Visitor *v, void **obj);
331 /*** Visiting lists ***/
334 * Start visiting a list.
336 * @name expresses the relationship of this list to its parent
337 * container; see the general description of @name above.
339 * @list must be non-NULL for a real walk, in which case @size
340 * determines how much memory an input or clone visitor will allocate
341 * into *@list (at least sizeof(GenericList)). Some visitors also
342 * allow @list to be NULL for a virtual walk, in which case @size is
343 * ignored.
345 * @errp obeys typical error usage, and reports failures such as a
346 * member @name is not present, or present but not a list. On error,
347 * input visitors set *@list to NULL.
349 * After visit_start_list() succeeds, the caller may visit its members
350 * one after the other. A real visit (where @obj is non-NULL) uses
351 * visit_next_list() for traversing the linked list, while a virtual
352 * visit (where @obj is NULL) uses other means. For each list
353 * element, call the appropriate visit_type_FOO() with name set to
354 * NULL and obj set to the address of the value member of the list
355 * element. Finally, visit_end_list() needs to be called with the
356 * same @list to clean up, even if intermediate visits fail. See the
357 * examples above.
359 void visit_start_list(Visitor *v, const char *name, GenericList **list,
360 size_t size, Error **errp);
363 * Iterate over a GenericList during a non-virtual list visit.
365 * @size represents the size of a linked list node (at least
366 * sizeof(GenericList)).
368 * @tail must not be NULL; on the first call, @tail is the value of
369 * *list after visit_start_list(), and on subsequent calls @tail must
370 * be the previously returned value. Should be called in a loop until
371 * a NULL return or error occurs; for each non-NULL return, the caller
372 * then calls the appropriate visit_type_*() for the element type of
373 * the list, with that function's name parameter set to NULL and obj
374 * set to the address of @tail->value.
376 GenericList *visit_next_list(Visitor *v, GenericList *tail, size_t size);
379 * Complete a list visit started earlier.
381 * @list must match what was passed to the paired visit_start_list().
383 * Must be called after any successful use of visit_start_list(), even
384 * if intermediate processing was skipped due to errors, to allow the
385 * backend to release any resources. Destroying the visitor early
386 * with visit_free() behaves as if this was implicitly called.
388 void visit_end_list(Visitor *v, void **list);
391 /*** Visiting alternates ***/
394 * Start the visit of an alternate @obj.
396 * @name expresses the relationship of this alternate to its parent
397 * container; see the general description of @name above.
399 * @obj must not be NULL. Input and clone visitors use @size to
400 * determine how much memory to allocate into *@obj, then determine
401 * the qtype of the next thing to be visited, stored in (*@obj)->type.
402 * Other visitors will leave @obj unchanged.
404 * If @promote_int, treat integers as QTYPE_FLOAT.
406 * If successful, this must be paired with visit_end_alternate() with
407 * the same @obj to clean up, even if visiting the contents of the
408 * alternate fails.
410 void visit_start_alternate(Visitor *v, const char *name,
411 GenericAlternate **obj, size_t size,
412 bool promote_int, Error **errp);
415 * Finish visiting an alternate type.
417 * @obj must match what was passed to the paired visit_start_alternate().
419 * Must be called after any successful use of visit_start_alternate(),
420 * even if intermediate processing was skipped due to errors, to allow
421 * the backend to release any resources. Destroying the visitor early
422 * with visit_free() behaves as if this was implicitly called.
425 void visit_end_alternate(Visitor *v, void **obj);
428 /*** Other helpers ***/
431 * Does optional struct member @name need visiting?
433 * @name must not be NULL. This function is only useful between
434 * visit_start_struct() and visit_end_struct(), since only objects
435 * have optional keys.
437 * @present points to the address of the optional member's has_ flag.
439 * Input visitors set *@present according to input; other visitors
440 * leave it unchanged. In either case, return *@present for
441 * convenience.
443 bool visit_optional(Visitor *v, const char *name, bool *present);
446 * Visit an enum value.
448 * @name expresses the relationship of this enum to its parent
449 * container; see the general description of @name above.
451 * @obj must be non-NULL. Input visitors parse input and set *@obj to
452 * the enumeration value, leaving @obj unchanged on error; other
453 * visitors use *@obj but leave it unchanged.
455 * Currently, all input visitors parse text input, and all output
456 * visitors produce text output. The mapping between enumeration
457 * values and strings is done by the visitor core, using @strings; it
458 * should be the ENUM_lookup array from visit-types.h.
460 * May call visit_type_str() under the hood, and the enum visit may
461 * fail even if the corresponding string visit succeeded; this implies
462 * that visit_type_str() must have no unwelcome side effects.
464 void visit_type_enum(Visitor *v, const char *name, int *obj,
465 const char *const strings[], Error **errp);
468 * Check if visitor is an input visitor.
470 bool visit_is_input(Visitor *v);
472 /*** Visiting built-in types ***/
475 * Visit an integer value.
477 * @name expresses the relationship of this integer to its parent
478 * container; see the general description of @name above.
480 * @obj must be non-NULL. Input visitors set *@obj to the value;
481 * other visitors will leave *@obj unchanged.
483 void visit_type_int(Visitor *v, const char *name, int64_t *obj, Error **errp);
486 * Visit a uint8_t value.
487 * Like visit_type_int(), except clamps the value to uint8_t range.
489 void visit_type_uint8(Visitor *v, const char *name, uint8_t *obj,
490 Error **errp);
493 * Visit a uint16_t value.
494 * Like visit_type_int(), except clamps the value to uint16_t range.
496 void visit_type_uint16(Visitor *v, const char *name, uint16_t *obj,
497 Error **errp);
500 * Visit a uint32_t value.
501 * Like visit_type_int(), except clamps the value to uint32_t range.
503 void visit_type_uint32(Visitor *v, const char *name, uint32_t *obj,
504 Error **errp);
507 * Visit a uint64_t value.
508 * Like visit_type_int(), except clamps the value to uint64_t range,
509 * that is, ensures it is unsigned.
511 void visit_type_uint64(Visitor *v, const char *name, uint64_t *obj,
512 Error **errp);
515 * Visit an int8_t value.
516 * Like visit_type_int(), except clamps the value to int8_t range.
518 void visit_type_int8(Visitor *v, const char *name, int8_t *obj, Error **errp);
521 * Visit an int16_t value.
522 * Like visit_type_int(), except clamps the value to int16_t range.
524 void visit_type_int16(Visitor *v, const char *name, int16_t *obj,
525 Error **errp);
528 * Visit an int32_t value.
529 * Like visit_type_int(), except clamps the value to int32_t range.
531 void visit_type_int32(Visitor *v, const char *name, int32_t *obj,
532 Error **errp);
535 * Visit an int64_t value.
536 * Identical to visit_type_int().
538 void visit_type_int64(Visitor *v, const char *name, int64_t *obj,
539 Error **errp);
542 * Visit a uint64_t value.
543 * Like visit_type_uint64(), except that some visitors may choose to
544 * recognize additional syntax, such as suffixes for easily scaling
545 * values.
547 void visit_type_size(Visitor *v, const char *name, uint64_t *obj,
548 Error **errp);
551 * Visit a boolean value.
553 * @name expresses the relationship of this boolean to its parent
554 * container; see the general description of @name above.
556 * @obj must be non-NULL. Input visitors set *@obj to the value;
557 * other visitors will leave *@obj unchanged.
559 void visit_type_bool(Visitor *v, const char *name, bool *obj, Error **errp);
562 * Visit a string value.
564 * @name expresses the relationship of this string to its parent
565 * container; see the general description of @name above.
567 * @obj must be non-NULL. Input and clone visitors set *@obj to the
568 * value (always using "" rather than NULL for an empty string).
569 * Other visitors leave *@obj unchanged, and commonly treat NULL like
570 * "".
572 * It is safe to cast away const when preparing a (const char *) value
573 * into @obj for use by an output visitor.
575 * FIXME: Callers that try to output NULL *obj should not be allowed.
577 void visit_type_str(Visitor *v, const char *name, char **obj, Error **errp);
580 * Visit a number (i.e. double) value.
582 * @name expresses the relationship of this number to its parent
583 * container; see the general description of @name above.
585 * @obj must be non-NULL. Input visitors set *@obj to the value;
586 * other visitors will leave *@obj unchanged. Visitors should
587 * document if infinity or NaN are not permitted.
589 void visit_type_number(Visitor *v, const char *name, double *obj,
590 Error **errp);
593 * Visit an arbitrary value.
595 * @name expresses the relationship of this value to its parent
596 * container; see the general description of @name above.
598 * @obj must be non-NULL. Input visitors set *@obj to the value;
599 * other visitors will leave *@obj unchanged. *@obj must be non-NULL
600 * for output visitors.
602 void visit_type_any(Visitor *v, const char *name, QObject **obj, Error **errp);
605 * Visit a JSON null value.
607 * @name expresses the relationship of the null value to its parent
608 * container; see the general description of @name above.
610 * Unlike all other visit_type_* functions, no obj parameter is
611 * needed; rather, this is a witness that an explicit null value is
612 * expected rather than any other type.
614 void visit_type_null(Visitor *v, const char *name, Error **errp);
616 #endif