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