]>
git.proxmox.com Git - mirror_qemu.git/blob - include/qapi/visitor.h
2 * Core Definitions for QAPI Visitor Classes
4 * Copyright (C) 2012-2016 Red Hat, Inc.
5 * Copyright IBM, Corp. 2011
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.
14 #ifndef QAPI_VISITOR_CORE_H
15 #define QAPI_VISITOR_CORE_H
17 #include "qapi/qmp/qobject.h"
20 * The QAPI schema defines both a set of C data types, and a QMP wire
21 * format. QAPI objects can contain references to other QAPI objects,
22 * resulting in a directed acyclic graph. QAPI also generates visitor
23 * functions to walk these graphs. This file represents the interface
24 * for doing work at each node of a QAPI graph; it can also be used
25 * for a virtual walk, where there is no actual QAPI C struct.
27 * There are three kinds of visitor classes: input visitors (QMP,
28 * string, and QemuOpts) parse an external representation and build
29 * the corresponding QAPI graph, output visitors (QMP and string) take
30 * a completed QAPI graph and generate an external representation, and
31 * the dealloc visitor can take a QAPI graph (possibly partially
32 * constructed) and recursively free its resources. While the dealloc
33 * and QMP input/output visitors are general, the string and QemuOpts
34 * visitors have some implementation limitations; see the
35 * documentation for each visitor for more details on what it
36 * supports. Also, see visitor-impl.h for the callback contracts
37 * implemented by each visitor, and docs/qapi-code-gen.txt for more
38 * about the QAPI code generator.
40 * All QAPI types have a corresponding function with a signature
41 * roughly compatible with this:
43 * void visit_type_FOO(Visitor *v, const char *name, T obj, Error **errp);
45 * where T is FOO for scalar types, and FOO * otherwise. The scalar
46 * visitors are declared here; the remaining visitors are generated in
49 * The @name parameter of visit_type_FOO() describes the relation
50 * between this QAPI value and its parent container. When visiting
51 * the root of a tree, @name is ignored; when visiting a member of an
52 * object, @name is the key associated with the value; and when
53 * visiting a member of a list, @name is NULL.
55 * FIXME: Clients must pass NULL for @name when visiting a member of a
56 * list, but this leads to poor error messages; it might be nicer to
57 * require a non-NULL name such as "key.0" for '{ "key": [ "value" ]
58 * }' if an error is encountered on "value" (or to have the visitor
59 * core auto-generate the nicer name).
61 * The visit_type_FOO() functions expect a non-null @obj argument;
62 * they allocate *@obj during input visits, leave it unchanged on
63 * output visits, and recursively free any resources during a dealloc
64 * visit. Each function also takes the customary @errp argument (see
65 * qapi/error.h for details), for reporting any errors (such as if a
66 * member @name is not present, or is present but not the specified
69 * FIXME: At present, visit_type_FOO() is an awkward interface: input
70 * visitors may allocate an incomplete *@obj even when reporting an
71 * error, but using an output visitor with an incomplete object has
72 * undefined behavior. To avoid a memory leak, callers must use
73 * qapi_free_FOO() even on error (this uses the dealloc visitor, and
74 * safely handles an incomplete object).
76 * For the QAPI object types (structs, unions, and alternates), there
77 * is an additional generated function in qapi-visit.h compatible
80 * void visit_type_FOO_members(Visitor *v, FOO *obj, Error **errp);
82 * for visiting the members of a type without also allocating the QAPI
85 * Additionally, in qapi-types.h, all QAPI pointer types (structs,
86 * unions, alternates, and lists) have a generated function compatible
89 * void qapi_free_FOO(FOO *obj);
91 * which behaves like free() in that @obj may be NULL. Because of
92 * these functions, the dealloc visitor is seldom used directly
93 * outside of generated code. QAPI types can also inherit from a base
94 * class; when this happens, a function is generated for easily going
95 * from the derived type to the base type:
97 * BASE *qapi_CHILD_base(CHILD *obj);
99 * For a real QAPI struct, typical input usage involves:
106 * v = ...obtain input visitor...
107 * visit_type_Foo(v, NULL, &f, &err);
124 * v = ...obtain input visitor...
125 * visit_type_FooList(v, NULL, &l, &err);
127 * qapi_free_FooList(l);
130 * for ( ; l; l = l->next) {
135 * qapi_free_FooList(l);
138 * Similarly, typical output usage is:
141 * Foo *f = ...obtain populated object...
145 * v = ...obtain output visitor...
146 * visit_type_Foo(v, NULL, &f, &err);
153 * When visiting a real QAPI struct, this file provides several
154 * helpers that rely on in-tree information to control the walk:
155 * visit_optional() for the 'has_member' field associated with
156 * optional 'member' in the C struct; and visit_next_list() for
157 * advancing through a FooList linked list. Only the generated
158 * visit_type functions need to use these helpers.
160 * It is also possible to use the visitors to do a virtual walk, where
161 * no actual QAPI struct is present. In this situation, decisions
162 * about what needs to be walked are made by the calling code, and
163 * structured visits are split between pairs of start and end methods
164 * (where the end method must be called if the start function
165 * succeeded, even if an intermediate visit encounters an error).
166 * Thus, a virtual walk corresponding to '{ "list": [1, 2] }' looks
174 * v = ...obtain visitor...
175 * visit_start_struct(v, NULL, NULL, 0, &err);
179 * visit_start_list(v, "list", &err);
184 * visit_type_int(v, NULL, &value, &err);
189 * visit_type_int(v, NULL, &value, &err);
196 * visit_check_struct(v, &err);
199 * visit_end_struct(v);
201 * error_propagate(errp, err);
206 /*** Useful types ***/
208 /* This struct is layout-compatible with all other *List structs
209 * created by the QAPI generator. It is used as a typical
210 * singly-linked list. */
211 typedef struct GenericList
{
212 struct GenericList
*next
;
216 /* This struct is layout-compatible with all Alternate types
217 * created by the QAPI generator. */
218 typedef struct GenericAlternate
{
223 /*** Visiting structures ***/
226 * Start visiting an object @obj (struct or union).
228 * @name expresses the relationship of this object to its parent
229 * container; see the general description of @name above.
231 * @obj must be non-NULL for a real walk, in which case @size
232 * determines how much memory an input visitor will allocate into
233 * *@obj. @obj may also be NULL for a virtual walk, in which case
236 * @errp obeys typical error usage, and reports failures such as a
237 * member @name is not present, or present but not an object. On
238 * error, input visitors set *@obj to NULL.
240 * After visit_start_struct() succeeds, the caller may visit its
241 * members one after the other, passing the member's name and address
242 * within the struct. Finally, visit_end_struct() needs to be called
243 * to clean up, even if intermediate visits fail. See the examples
246 * FIXME Should this be named visit_start_object, since it is also
247 * used for QAPI unions, and maps to JSON objects?
249 void visit_start_struct(Visitor
*v
, const char *name
, void **obj
,
250 size_t size
, Error
**errp
);
253 * Prepare for completing an object visit.
255 * @errp obeys typical error usage, and reports failures such as
256 * unparsed keys remaining in the input stream.
258 * Should be called prior to visit_end_struct() if all other
259 * intermediate visit steps were successful, to allow the visitor one
260 * last chance to report errors. May be skipped on a cleanup path,
261 * where there is no need to check for further errors.
263 void visit_check_struct(Visitor
*v
, Error
**errp
);
266 * Complete an object visit started earlier.
268 * Must be called after any successful use of visit_start_struct(),
269 * even if intermediate processing was skipped due to errors, to allow
270 * the backend to release any resources. Destroying the visitor early
271 * behaves as if this was implicitly called.
273 void visit_end_struct(Visitor
*v
);
276 /*** Visiting lists ***/
279 * Start visiting a list.
281 * @name expresses the relationship of this list to its parent
282 * container; see the general description of @name above.
284 * @errp obeys typical error usage, and reports failures such as a
285 * member @name is not present, or present but not a list.
287 * After visit_start_list() succeeds, the caller may visit its members
288 * one after the other. A real visit uses visit_next_list() for
289 * traversing the linked list, while a virtual visit uses other means.
290 * For each list element, call the appropriate visit_type_FOO() with
291 * name set to NULL and obj set to the address of the value member of
292 * the list element. Finally, visit_end_list() needs to be called to
293 * clean up, even if intermediate visits fail. See the examples
296 void visit_start_list(Visitor
*v
, const char *name
, Error
**errp
);
299 * Iterate over a GenericList during a non-virtual list visit.
301 * @size represents the size of a linked list node (at least
302 * sizeof(GenericList)).
304 * @list must not be NULL; on the first call, @list contains the
305 * address of the list head, and on subsequent calls *@list must be
306 * the previously returned value. Should be called in a loop until a
307 * NULL return or error occurs; for each non-NULL return, the caller
308 * then calls the appropriate visit_type_*() for the element type
309 * of the list, with that function's name parameter set to NULL and
310 * obj set to the address of (*@list)->value.
312 * FIXME: This interface is awkward; it requires all callbacks to
313 * track whether it is the first or a subsequent call. A better
314 * interface would pass the head of the list through
315 * visit_start_list().
317 GenericList
*visit_next_list(Visitor
*v
, GenericList
**list
, size_t size
);
320 * Complete a list visit started earlier.
322 * Must be called after any successful use of visit_start_list(), even
323 * if intermediate processing was skipped due to errors, to allow the
324 * backend to release any resources. Destroying the visitor early
325 * behaves as if this was implicitly called.
327 void visit_end_list(Visitor
*v
);
330 /*** Visiting alternates ***/
333 * Start the visit of an alternate @obj.
335 * @name expresses the relationship of this alternate to its parent
336 * container; see the general description of @name above.
338 * @obj must not be NULL. Input visitors use @size to determine how
339 * much memory to allocate into *@obj, then determine the qtype of the
340 * next thing to be visited, stored in (*@obj)->type. Other visitors
341 * will leave @obj unchanged.
343 * If @promote_int, treat integers as QTYPE_FLOAT.
345 * If successful, this must be paired with visit_end_alternate() to
346 * clean up, even if visiting the contents of the alternate fails.
348 void visit_start_alternate(Visitor
*v
, const char *name
,
349 GenericAlternate
**obj
, size_t size
,
350 bool promote_int
, Error
**errp
);
353 * Finish visiting an alternate type.
355 * Must be called after any successful use of visit_start_alternate(),
356 * even if intermediate processing was skipped due to errors, to allow
357 * the backend to release any resources. Destroying the visitor early
358 * behaves as if this was implicitly called.
360 * TODO: Should all the visit_end_* interfaces take obj parameter, so
361 * that dealloc visitor need not track what was passed in visit_start?
363 void visit_end_alternate(Visitor
*v
);
366 /*** Other helpers ***/
369 * Does optional struct member @name need visiting?
371 * @name must not be NULL. This function is only useful between
372 * visit_start_struct() and visit_end_struct(), since only objects
373 * have optional keys.
375 * @present points to the address of the optional member's has_ flag.
377 * Input visitors set *@present according to input; other visitors
378 * leave it unchanged. In either case, return *@present for
381 bool visit_optional(Visitor
*v
, const char *name
, bool *present
);
384 * Visit an enum value.
386 * @name expresses the relationship of this enum to its parent
387 * container; see the general description of @name above.
389 * @obj must be non-NULL. Input visitors parse input and set *@obj to
390 * the enumeration value, leaving @obj unchanged on error; other
391 * visitors use *@obj but leave it unchanged.
393 * Currently, all input visitors parse text input, and all output
394 * visitors produce text output. The mapping between enumeration
395 * values and strings is done by the visitor core, using @strings; it
396 * should be the ENUM_lookup array from visit-types.h.
398 * May call visit_type_str() under the hood, and the enum visit may
399 * fail even if the corresponding string visit succeeded; this implies
400 * that visit_type_str() must have no unwelcome side effects.
402 void visit_type_enum(Visitor
*v
, const char *name
, int *obj
,
403 const char *const strings
[], Error
**errp
);
405 /*** Visiting built-in types ***/
408 * Visit an integer value.
410 * @name expresses the relationship of this integer to its parent
411 * container; see the general description of @name above.
413 * @obj must be non-NULL. Input visitors set *@obj to the value;
414 * other visitors will leave *@obj unchanged.
416 void visit_type_int(Visitor
*v
, const char *name
, int64_t *obj
, Error
**errp
);
419 * Visit a uint8_t value.
420 * Like visit_type_int(), except clamps the value to uint8_t range.
422 void visit_type_uint8(Visitor
*v
, const char *name
, uint8_t *obj
,
426 * Visit a uint16_t value.
427 * Like visit_type_int(), except clamps the value to uint16_t range.
429 void visit_type_uint16(Visitor
*v
, const char *name
, uint16_t *obj
,
433 * Visit a uint32_t value.
434 * Like visit_type_int(), except clamps the value to uint32_t range.
436 void visit_type_uint32(Visitor
*v
, const char *name
, uint32_t *obj
,
440 * Visit a uint64_t value.
441 * Like visit_type_int(), except clamps the value to uint64_t range,
442 * that is, ensures it is unsigned.
444 void visit_type_uint64(Visitor
*v
, const char *name
, uint64_t *obj
,
448 * Visit an int8_t value.
449 * Like visit_type_int(), except clamps the value to int8_t range.
451 void visit_type_int8(Visitor
*v
, const char *name
, int8_t *obj
, Error
**errp
);
454 * Visit an int16_t value.
455 * Like visit_type_int(), except clamps the value to int16_t range.
457 void visit_type_int16(Visitor
*v
, const char *name
, int16_t *obj
,
461 * Visit an int32_t value.
462 * Like visit_type_int(), except clamps the value to int32_t range.
464 void visit_type_int32(Visitor
*v
, const char *name
, int32_t *obj
,
468 * Visit an int64_t value.
469 * Identical to visit_type_int().
471 void visit_type_int64(Visitor
*v
, const char *name
, int64_t *obj
,
475 * Visit a uint64_t value.
476 * Like visit_type_uint64(), except that some visitors may choose to
477 * recognize additional syntax, such as suffixes for easily scaling
480 void visit_type_size(Visitor
*v
, const char *name
, uint64_t *obj
,
484 * Visit a boolean value.
486 * @name expresses the relationship of this boolean to its parent
487 * container; see the general description of @name above.
489 * @obj must be non-NULL. Input visitors set *@obj to the value;
490 * other visitors will leave *@obj unchanged.
492 void visit_type_bool(Visitor
*v
, const char *name
, bool *obj
, Error
**errp
);
495 * Visit a string value.
497 * @name expresses the relationship of this string to its parent
498 * container; see the general description of @name above.
500 * @obj must be non-NULL. Input visitors set *@obj to the value
501 * (never NULL). Other visitors leave *@obj unchanged, and commonly
502 * treat NULL like "".
504 * It is safe to cast away const when preparing a (const char *) value
505 * into @obj for use by an output visitor.
507 * FIXME: Callers that try to output NULL *obj should not be allowed.
509 void visit_type_str(Visitor
*v
, const char *name
, char **obj
, Error
**errp
);
512 * Visit a number (i.e. double) value.
514 * @name expresses the relationship of this number to its parent
515 * container; see the general description of @name above.
517 * @obj must be non-NULL. Input visitors set *@obj to the value;
518 * other visitors will leave *@obj unchanged. Visitors should
519 * document if infinity or NaN are not permitted.
521 void visit_type_number(Visitor
*v
, const char *name
, double *obj
,
525 * Visit an arbitrary value.
527 * @name expresses the relationship of this value to its parent
528 * container; see the general description of @name above.
530 * @obj must be non-NULL. Input visitors set *@obj to the value;
531 * other visitors will leave *@obj unchanged. *@obj must be non-NULL
532 * for output visitors.
534 void visit_type_any(Visitor
*v
, const char *name
, QObject
**obj
, Error
**errp
);
537 * Visit a JSON null value.
539 * @name expresses the relationship of the null value to its parent
540 * container; see the general description of @name above.
542 * Unlike all other visit_type_* functions, no obj parameter is
543 * needed; rather, this is a witness that an explicit null value is
544 * expected rather than any other type.
546 void visit_type_null(Visitor
*v
, const char *name
, Error
**errp
);