Merge remote-tracking branch 'remotes/vivier2/tags/trivial-branch-for-5.2-pull-reques...
[qemu.git] / include / qapi / visitor.h
1 /*
2 * Core Definitions for QAPI Visitor Classes
3 *
4 * Copyright (C) 2012-2016 Red Hat, Inc.
5 * Copyright IBM, Corp. 2011
6 *
7 * Authors:
8 * Anthony Liguori <aliguori@us.ibm.com>
9 *
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.
12 *
13 */
14
15 #ifndef QAPI_VISITOR_H
16 #define QAPI_VISITOR_H
17
18 #include "qapi/qapi-builtin-types.h"
19
20 /*
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.
27 *
28 * There are four kinds of visitors: input visitors (QObject, string,
29 * and QemuOpts) parse an external representation and build the
30 * corresponding QAPI object, output visitors (QObject and string)
31 * take a QAPI object and generate an external representation, the
32 * dealloc visitor takes a QAPI object (possibly partially
33 * constructed) and recursively frees it, and the clone visitor
34 * performs a deep clone of a QAPI object.
35 *
36 * While the dealloc and QObject input/output visitors are general,
37 * the string, QemuOpts, and clone visitors have some implementation
38 * limitations; see the documentation for each visitor for more
39 * details on what it supports. Also, see visitor-impl.h for the
40 * callback contracts implemented by each visitor, and
41 * docs/devel/qapi-code-gen.txt for more about the QAPI code
42 * generator.
43 *
44 * All of the visitors are created via:
45 *
46 * Visitor *subtype_visitor_new(parameters...);
47 *
48 * A visitor should be used for exactly one top-level visit_type_FOO()
49 * or virtual walk; if that is successful, the caller can optionally
50 * call visit_complete() (useful only for output visits, but safe to
51 * call on all visits). Then, regardless of success or failure, the
52 * user should call visit_free() to clean up resources. It is okay to
53 * free the visitor without completing the visit, if some other error
54 * is detected in the meantime.
55 *
56 * The clone and dealloc visitor should not be used directly outside
57 * of QAPI code. Use the qapi_free_FOO() and QAPI_CLONE() instead,
58 * described below.
59 *
60 * All QAPI types have a corresponding function with a signature
61 * roughly compatible with this:
62 *
63 * bool visit_type_FOO(Visitor *v, const char *name, T obj, Error **errp);
64 *
65 * where T is FOO for scalar types, and FOO * otherwise. The scalar
66 * visitors are declared here; the remaining visitors are generated in
67 * qapi-visit-MODULE.h.
68 *
69 * The @name parameter of visit_type_FOO() describes the relation
70 * between this QAPI value and its parent container. When visiting
71 * the root of a tree, @name is ignored; when visiting a member of an
72 * object, @name is the key associated with the value; when visiting a
73 * member of a list, @name is NULL; and when visiting the member of an
74 * alternate, @name should equal the name used for visiting the
75 * alternate.
76 *
77 * The visit_type_FOO() functions take a non-null @obj argument; they
78 * allocate *@obj during input visits, leave it unchanged during
79 * output and clone visits, and free it (recursively) during a dealloc
80 * visit.
81 *
82 * Each function also takes the customary @errp argument (see
83 * qapi/error.h for details), for reporting any errors (such as if a
84 * member @name is not present, or is present but not the specified
85 * type). Only input visitors can fail.
86 *
87 * If an error is detected during visit_type_FOO() with an input
88 * visitor, then *@obj will be set to NULL for pointer types, and left
89 * unchanged for scalar types.
90 *
91 * Using an output or clone visitor with an incomplete object has
92 * undefined behavior (other than a special case for visit_type_str()
93 * treating NULL like ""), while the dealloc visitor safely handles
94 * incomplete objects. Since input visitors never produce an
95 * incomplete object, such an object is possible only by manual
96 * construction.
97 *
98 * visit_type_FOO() returns true on success, false on error.
99 *
100 * For the QAPI object types (structs, unions, and alternates), there
101 * is an additional generated function in qapi-visit-MODULE.h
102 * compatible with:
103 *
104 * bool visit_type_FOO_members(Visitor *v, FOO *obj, Error **errp);
105 *
106 * for visiting the members of a type without also allocating the QAPI
107 * struct. It also returns true on success, false on error.
108 *
109 * Additionally, QAPI pointer types (structs, unions, alternates, and
110 * lists) have a generated function in qapi-types-MODULE.h compatible
111 * with:
112 *
113 * void qapi_free_FOO(FOO *obj);
114 *
115 * Does nothing when @obj is NULL.
116 *
117 * Such objects may also be used with macro
118 *
119 * Type *QAPI_CLONE(Type, src);
120 *
121 * in order to perform a deep clone of @src.
122 *
123 * For QAPI types can that inherit from a base type, a function is
124 * generated for going from the derived type to the base type:
125 *
126 * BASE *qapi_CHILD_base(CHILD *obj);
127 *
128 * Typical input visitor usage involves:
129 *
130 * <example>
131 * Foo *f;
132 * Error *err = NULL;
133 * Visitor *v;
134 *
135 * v = FOO_visitor_new(...);
136 * if (!visit_type_Foo(v, NULL, &f, &err)) {
137 * ...handle error...
138 * } else {
139 * ...use f...
140 * }
141 * visit_free(v);
142 * qapi_free_Foo(f);
143 * </example>
144 *
145 * For a list, it is:
146 * <example>
147 * FooList *l;
148 * Error *err = NULL;
149 * Visitor *v;
150 *
151 * v = FOO_visitor_new(...);
152 * if (!visit_type_FooList(v, NULL, &l, &err)) {
153 * ...handle error...
154 * } else {
155 * for ( ; l; l = l->next) {
156 * ...use l->value...
157 * }
158 * }
159 * visit_free(v);
160 * qapi_free_FooList(l);
161 * </example>
162 *
163 * Typical output visitor usage:
164 *
165 * <example>
166 * Foo *f = ...obtain populated object...
167 * Visitor *v;
168 * Type *result;
169 *
170 * v = FOO_visitor_new(..., &result);
171 * visit_type_Foo(v, NULL, &f, &error_abort);
172 * visit_complete(v, &result);
173 * visit_free(v);
174 * ...use result...
175 * </example>
176 *
177 * It is also possible to use the visitors to do a virtual walk, where
178 * no actual QAPI object is present. In this situation, decisions
179 * about what needs to be walked are made by the calling code, and
180 * structured visits are split between pairs of start and end methods
181 * (where the end method must be called if the start function
182 * succeeded, even if an intermediate visit encounters an error).
183 * Thus, a virtual walk corresponding to '{ "list": [1, 2] }' looks
184 * like:
185 *
186 * <example>
187 * Visitor *v;
188 * Error *err = NULL;
189 * bool ok = false;
190 * int value;
191 *
192 * v = FOO_visitor_new(...);
193 * if (!visit_start_struct(v, NULL, NULL, 0, &err)) {
194 * goto out;
195 * }
196 * if (!visit_start_list(v, "list", NULL, 0, &err)) {
197 * goto outobj;
198 * }
199 * value = 1;
200 * if (!visit_type_int(v, NULL, &value, &err)) {
201 * goto outlist;
202 * }
203 * value = 2;
204 * if (!visit_type_int(v, NULL, &value, &err)) {
205 * goto outlist;
206 * }
207 * ok = true;
208 * outlist:
209 * if (ok) {
210 * ok = visit_check_list(v, &err);
211 * }
212 * visit_end_list(v, NULL);
213 * if (ok) {
214 * ok = visit_check_struct(v, &err);
215 * }
216 * outobj:
217 * visit_end_struct(v, NULL);
218 * out:
219 * visit_free(v);
220 * </example>
221 *
222 * This file provides helpers for use by the generated
223 * visit_type_FOO(): visit_optional() for the 'has_member' field
224 * associated with optional 'member' in the C struct,
225 * visit_next_list() for advancing through a FooList linked list, and
226 * visit_is_input() for cleaning up on failure.
227 */
228
229 /*** Useful types ***/
230
231 /* This struct is layout-compatible with all other *List structs
232 * created by the QAPI generator. It is used as a typical
233 * singly-linked list. */
234 typedef struct GenericList {
235 struct GenericList *next;
236 char padding[];
237 } GenericList;
238
239 /* This struct is layout-compatible with all Alternate types
240 * created by the QAPI generator. */
241 typedef struct GenericAlternate {
242 QType type;
243 char padding[];
244 } GenericAlternate;
245
246 /*** Visitor cleanup ***/
247
248 /*
249 * Complete the visit, collecting any output.
250 *
251 * May only be called only once after a successful top-level
252 * visit_type_FOO() or visit_end_ITEM(), and marks the end of the
253 * visit. The @opaque pointer should match the output parameter
254 * passed to the subtype_visitor_new() used to create an output
255 * visitor, or NULL for any other visitor. Needed for output
256 * visitors, but may also be called with other visitors.
257 */
258 void visit_complete(Visitor *v, void *opaque);
259
260 /*
261 * Free @v and any resources it has tied up.
262 *
263 * May be called whether or not the visit has been successfully
264 * completed, but should not be called until a top-level
265 * visit_type_FOO() or visit_start_ITEM() has been performed on the
266 * visitor. Safe if @v is NULL.
267 */
268 void visit_free(Visitor *v);
269
270
271 /*** Visiting structures ***/
272
273 /*
274 * Start visiting an object @obj (struct or union).
275 *
276 * @name expresses the relationship of this object to its parent
277 * container; see the general description of @name above.
278 *
279 * @obj must be non-NULL for a real walk, in which case @size
280 * determines how much memory an input or clone visitor will allocate
281 * into *@obj. @obj may also be NULL for a virtual walk, in which
282 * case @size is ignored.
283 *
284 * On failure, set *@obj to NULL and store an error through @errp.
285 * Can happen only when @v is an input visitor.
286 *
287 * Return true on success, false on failure.
288 *
289 * After visit_start_struct() succeeds, the caller may visit its
290 * members one after the other, passing the member's name and address
291 * within the struct. Finally, visit_end_struct() needs to be called
292 * with the same @obj to clean up, even if intermediate visits fail.
293 * See the examples above.
294 *
295 * FIXME Should this be named visit_start_object, since it is also
296 * used for QAPI unions, and maps to JSON objects?
297 */
298 bool visit_start_struct(Visitor *v, const char *name, void **obj,
299 size_t size, Error **errp);
300
301 /*
302 * Prepare for completing an object visit.
303 *
304 * On failure, store an error through @errp. Can happen only when @v
305 * is an input visitor.
306 *
307 * Return true on success, false on failure.
308 *
309 * Should be called prior to visit_end_struct() if all other
310 * intermediate visit steps were successful, to allow the visitor one
311 * last chance to report errors. May be skipped on a cleanup path,
312 * where there is no need to check for further errors.
313 */
314 bool visit_check_struct(Visitor *v, Error **errp);
315
316 /*
317 * Complete an object visit started earlier.
318 *
319 * @obj must match what was passed to the paired visit_start_struct().
320 *
321 * Must be called after any successful use of visit_start_struct(),
322 * even if intermediate processing was skipped due to errors, to allow
323 * the backend to release any resources. Destroying the visitor early
324 * with visit_free() behaves as if this was implicitly called.
325 */
326 void visit_end_struct(Visitor *v, void **obj);
327
328
329 /*** Visiting lists ***/
330
331 /*
332 * Start visiting a list.
333 *
334 * @name expresses the relationship of this list to its parent
335 * container; see the general description of @name above.
336 *
337 * @list must be non-NULL for a real walk, in which case @size
338 * determines how much memory an input or clone visitor will allocate
339 * into *@list (at least sizeof(GenericList)). Some visitors also
340 * allow @list to be NULL for a virtual walk, in which case @size is
341 * ignored.
342 *
343 * On failure, set *@list to NULL and store an error through @errp.
344 * Can happen only when @v is an input visitor.
345 *
346 * Return true on success, false on failure.
347 *
348 * After visit_start_list() succeeds, the caller may visit its members
349 * one after the other. A real visit (where @list is non-NULL) uses
350 * visit_next_list() for traversing the linked list, while a virtual
351 * visit (where @list is NULL) uses other means. For each list
352 * element, call the appropriate visit_type_FOO() with name set to
353 * NULL and obj set to the address of the value member of the list
354 * element. Finally, visit_end_list() needs to be called with the
355 * same @list to clean up, even if intermediate visits fail. See the
356 * examples above.
357 */
358 bool visit_start_list(Visitor *v, const char *name, GenericList **list,
359 size_t size, Error **errp);
360
361 /*
362 * Iterate over a GenericList during a non-virtual list visit.
363 *
364 * @size represents the size of a linked list node (at least
365 * sizeof(GenericList)).
366 *
367 * @tail must not be NULL; on the first call, @tail is the value of
368 * *list after visit_start_list(), and on subsequent calls @tail must
369 * be the previously returned value. Should be called in a loop until
370 * a NULL return; for each non-NULL return, the caller then calls the
371 * appropriate visit_type_*() for the element type of the list, with
372 * that function's name parameter set to NULL and obj set to the
373 * address of @tail->value.
374 */
375 GenericList *visit_next_list(Visitor *v, GenericList *tail, size_t size);
376
377 /*
378 * Prepare for completing a list visit.
379 *
380 * On failure, store an error through @errp. Can happen only when @v
381 * is an input visitor.
382 *
383 * Return true on success, false on failure.
384 *
385 * Should be called prior to visit_end_list() if all other
386 * intermediate visit steps were successful, to allow the visitor one
387 * last chance to report errors. May be skipped on a cleanup path,
388 * where there is no need to check for further errors.
389 */
390 bool visit_check_list(Visitor *v, Error **errp);
391
392 /*
393 * Complete a list visit started earlier.
394 *
395 * @list must match what was passed to the paired visit_start_list().
396 *
397 * Must be called after any successful use of visit_start_list(), even
398 * if intermediate processing was skipped due to errors, to allow the
399 * backend to release any resources. Destroying the visitor early
400 * with visit_free() behaves as if this was implicitly called.
401 */
402 void visit_end_list(Visitor *v, void **list);
403
404
405 /*** Visiting alternates ***/
406
407 /*
408 * Start the visit of an alternate @obj.
409 *
410 * @name expresses the relationship of this alternate to its parent
411 * container; see the general description of @name above.
412 *
413 * @obj must not be NULL. Input and clone visitors use @size to
414 * determine how much memory to allocate into *@obj, then determine
415 * the qtype of the next thing to be visited, and store it in
416 * (*@obj)->type. Other visitors leave @obj unchanged.
417 *
418 * On failure, set *@obj to NULL and store an error through @errp.
419 * Can happen only when @v is an input visitor.
420 *
421 * Return true on success, false on failure.
422 *
423 * If successful, this must be paired with visit_end_alternate() with
424 * the same @obj to clean up, even if visiting the contents of the
425 * alternate fails.
426 */
427 bool visit_start_alternate(Visitor *v, const char *name,
428 GenericAlternate **obj, size_t size,
429 Error **errp);
430
431 /*
432 * Finish visiting an alternate type.
433 *
434 * @obj must match what was passed to the paired visit_start_alternate().
435 *
436 * Must be called after any successful use of visit_start_alternate(),
437 * even if intermediate processing was skipped due to errors, to allow
438 * the backend to release any resources. Destroying the visitor early
439 * with visit_free() behaves as if this was implicitly called.
440 *
441 */
442 void visit_end_alternate(Visitor *v, void **obj);
443
444
445 /*** Other helpers ***/
446
447 /*
448 * Does optional struct member @name need visiting?
449 *
450 * @name must not be NULL. This function is only useful between
451 * visit_start_struct() and visit_end_struct(), since only objects
452 * have optional keys.
453 *
454 * @present points to the address of the optional member's has_ flag.
455 *
456 * Input visitors set *@present according to input; other visitors
457 * leave it unchanged. In either case, return *@present for
458 * convenience.
459 */
460 bool visit_optional(Visitor *v, const char *name, bool *present);
461
462 /*
463 * Visit an enum value.
464 *
465 * @name expresses the relationship of this enum to its parent
466 * container; see the general description of @name above.
467 *
468 * @obj must be non-NULL. Input visitors parse input and set *@obj to
469 * the enumeration value, leaving @obj unchanged on error; other
470 * visitors use *@obj but leave it unchanged.
471 *
472 * Currently, all input visitors parse text input, and all output
473 * visitors produce text output. The mapping between enumeration
474 * values and strings is done by the visitor core, using @lookup.
475 *
476 * On failure, store an error through @errp. Can happen only when @v
477 * is an input visitor.
478 *
479 * Return true on success, false on failure.
480 *
481 * May call visit_type_str() under the hood, and the enum visit may
482 * fail even if the corresponding string visit succeeded; this implies
483 * that an input visitor's visit_type_str() must have no unwelcome
484 * side effects.
485 */
486 bool visit_type_enum(Visitor *v, const char *name, int *obj,
487 const QEnumLookup *lookup, Error **errp);
488
489 /*
490 * Check if visitor is an input visitor.
491 */
492 bool visit_is_input(Visitor *v);
493
494 /*
495 * Check if visitor is a dealloc visitor.
496 */
497 bool visit_is_dealloc(Visitor *v);
498
499 /*** Visiting built-in types ***/
500
501 /*
502 * Visit an integer value.
503 *
504 * @name expresses the relationship of this integer to its parent
505 * container; see the general description of @name above.
506 *
507 * @obj must be non-NULL. Input visitors set *@obj to the value;
508 * other visitors will leave *@obj unchanged.
509 *
510 * On failure, store an error through @errp. Can happen only when @v
511 * is an input visitor.
512 *
513 * Return true on success, false on failure.
514 */
515 bool visit_type_int(Visitor *v, const char *name, int64_t *obj, Error **errp);
516
517 /*
518 * Visit a uint8_t value.
519 * Like visit_type_int(), except clamps the value to uint8_t range.
520 */
521 bool visit_type_uint8(Visitor *v, const char *name, uint8_t *obj,
522 Error **errp);
523
524 /*
525 * Visit a uint16_t value.
526 * Like visit_type_int(), except clamps the value to uint16_t range.
527 */
528 bool visit_type_uint16(Visitor *v, const char *name, uint16_t *obj,
529 Error **errp);
530
531 /*
532 * Visit a uint32_t value.
533 * Like visit_type_int(), except clamps the value to uint32_t range.
534 */
535 bool visit_type_uint32(Visitor *v, const char *name, uint32_t *obj,
536 Error **errp);
537
538 /*
539 * Visit a uint64_t value.
540 * Like visit_type_int(), except clamps the value to uint64_t range,
541 * that is, ensures it is unsigned.
542 */
543 bool visit_type_uint64(Visitor *v, const char *name, uint64_t *obj,
544 Error **errp);
545
546 /*
547 * Visit an int8_t value.
548 * Like visit_type_int(), except clamps the value to int8_t range.
549 */
550 bool visit_type_int8(Visitor *v, const char *name, int8_t *obj, Error **errp);
551
552 /*
553 * Visit an int16_t value.
554 * Like visit_type_int(), except clamps the value to int16_t range.
555 */
556 bool visit_type_int16(Visitor *v, const char *name, int16_t *obj,
557 Error **errp);
558
559 /*
560 * Visit an int32_t value.
561 * Like visit_type_int(), except clamps the value to int32_t range.
562 */
563 bool visit_type_int32(Visitor *v, const char *name, int32_t *obj,
564 Error **errp);
565
566 /*
567 * Visit an int64_t value.
568 * Identical to visit_type_int().
569 */
570 bool visit_type_int64(Visitor *v, const char *name, int64_t *obj,
571 Error **errp);
572
573 /*
574 * Visit a uint64_t value.
575 * Like visit_type_uint64(), except that some visitors may choose to
576 * recognize additional syntax, such as suffixes for easily scaling
577 * values.
578 */
579 bool visit_type_size(Visitor *v, const char *name, uint64_t *obj,
580 Error **errp);
581
582 /*
583 * Visit a boolean value.
584 *
585 * @name expresses the relationship of this boolean to its parent
586 * container; see the general description of @name above.
587 *
588 * @obj must be non-NULL. Input visitors set *@obj to the value;
589 * other visitors will leave *@obj unchanged.
590 *
591 * On failure, store an error through @errp. Can happen only when @v
592 * is an input visitor.
593 *
594 * Return true on success, false on failure.
595 */
596 bool visit_type_bool(Visitor *v, const char *name, bool *obj, Error **errp);
597
598 /*
599 * Visit a string value.
600 *
601 * @name expresses the relationship of this string to its parent
602 * container; see the general description of @name above.
603 *
604 * @obj must be non-NULL. Input and clone visitors set *@obj to the
605 * value (always using "" rather than NULL for an empty string).
606 * Other visitors leave *@obj unchanged, and commonly treat NULL like
607 * "".
608 *
609 * It is safe to cast away const when preparing a (const char *) value
610 * into @obj for use by an output visitor.
611 *
612 * On failure, set *@obj to NULL and store an error through @errp.
613 * Can happen only when @v is an input visitor.
614 *
615 * Return true on success, false on failure.
616 *
617 * FIXME: Callers that try to output NULL *obj should not be allowed.
618 */
619 bool visit_type_str(Visitor *v, const char *name, char **obj, Error **errp);
620
621 /*
622 * Visit a number (i.e. double) value.
623 *
624 * @name expresses the relationship of this number to its parent
625 * container; see the general description of @name above.
626 *
627 * @obj must be non-NULL. Input visitors set *@obj to the value;
628 * other visitors will leave *@obj unchanged. Visitors should
629 * document if infinity or NaN are not permitted.
630 *
631 * On failure, store an error through @errp. Can happen only when @v
632 * is an input visitor.
633 *
634 * Return true on success, false on failure.
635 */
636 bool visit_type_number(Visitor *v, const char *name, double *obj,
637 Error **errp);
638
639 /*
640 * Visit an arbitrary value.
641 *
642 * @name expresses the relationship of this value to its parent
643 * container; see the general description of @name above.
644 *
645 * @obj must be non-NULL. Input visitors set *@obj to the value;
646 * other visitors will leave *@obj unchanged. *@obj must be non-NULL
647 * for output visitors.
648 *
649 * On failure, set *@obj to NULL and store an error through @errp.
650 * Can happen only when @v is an input visitor.
651 *
652 * Return true on success, false on failure.
653 *
654 * Note that some kinds of input can't express arbitrary QObject.
655 * E.g. the visitor returned by qobject_input_visitor_new_keyval()
656 * can't create numbers or booleans, only strings.
657 */
658 bool visit_type_any(Visitor *v, const char *name, QObject **obj, Error **errp);
659
660 /*
661 * Visit a JSON null value.
662 *
663 * @name expresses the relationship of the null value to its parent
664 * container; see the general description of @name above.
665 *
666 * @obj must be non-NULL. Input visitors set *@obj to the value;
667 * other visitors ignore *@obj.
668 *
669 * On failure, set *@obj to NULL and store an error through @errp.
670 * Can happen only when @v is an input visitor.
671 *
672 * Return true on success, false on failure.
673 */
674 bool visit_type_null(Visitor *v, const char *name, QNull **obj,
675 Error **errp);
676
677 #endif