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