linux-dev - Linux kernel development work

diff options

Diffstat (limited to 'scripts/const_structs.checkpatch')

0 files changed, 0 insertions, 0 deletions

/* * Core Definitions for QAPI Visitor Classes * * Copyright (C) 2012-2016 Red Hat, Inc. * Copyright IBM, Corp. 2011 * * Authors: * Anthony Liguori <aliguori@us.ibm.com> * * This work is licensed under the terms of the GNU LGPL, version 2.1 or later. * See the COPYING.LIB file in the top-level directory. * */ #ifndef QAPI_VISITOR_H #define QAPI_VISITOR_H #include "qapi/qmp/qobject.h" /* * The QAPI schema defines both a set of C data types, and a QMP wire * format. QAPI objects can contain references to other QAPI objects, * resulting in a directed acyclic graph. QAPI also generates visitor * functions to walk these graphs. This file represents the interface * for doing work at each node of a QAPI graph; it can also be used * for a virtual walk, where there is no actual QAPI C struct. * * There are four kinds of visitor classes: input visitors (QObject, * string, and QemuOpts) parse an external representation and build * the corresponding QAPI graph, output visitors (QObject and string) take * a completed QAPI graph and generate an external representation, the * dealloc visitor can take a QAPI graph (possibly partially * constructed) and recursively free its resources, and the clone * visitor performs a deep clone of one QAPI object to another. While * the dealloc and QObject input/output visitors are general, the string, * QemuOpts, and clone visitors have some implementation limitations; * see the documentation for each visitor for more details on what it * supports. Also, see visitor-impl.h for the callback contracts * implemented by each visitor, and docs/qapi-code-gen.txt for more * about the QAPI code generator. * * All of the visitors are created via: * * Visitor *subtype_visitor_new(parameters...); * * A visitor should be used for exactly one top-level visit_type_FOO() * or virtual walk; if that is successful, the caller can optionally * call visit_complete() (for now, useful only for output visits, but * safe to call on all visits). Then, regardless of success or * failure, the user should call visit_free() to clean up resources. * It is okay to free the visitor without completing the visit, if * some other error is detected in the meantime. * * All QAPI types have a corresponding function with a signature * roughly compatible with this: * * void visit_type_FOO(Visitor *v, const char *name, T obj, Error **errp); * * where T is FOO for scalar types, and FOO * otherwise. The scalar * visitors are declared here; the remaining visitors are generated in * qapi-visit.h. * * The @name parameter of visit_type_FOO() describes the relation * between this QAPI value and its parent container. When visiting * the root of a tree, @name is ignored; when visiting a member of an * object, @name is the key associated with the value; and when * visiting a member of a list, @name is NULL. * * FIXME: Clients must pass NULL for @name when visiting a member of a * list, but this leads to poor error messages; it might be nicer to * require a non-NULL name such as "key.0" for '{ "key": [ "value" ] * }' if an error is encountered on "value" (or to have the visitor * core auto-generate the nicer name). * * The visit_type_FOO() functions expect a non-null @obj argument; * they allocate *@obj during input visits, leave it unchanged on * output visits, and recursively free any resources during a dealloc * visit. Each function also takes the customary @errp argument (see * qapi/error.h for details), for reporting any errors (such as if a * member @name is not present, or is present but not the specified * type). * * If an error is detected during visit_type_FOO() with an input * visitor, then *@obj will be NULL for pointer types, and left * unchanged for scalar types. Using an output or clone visitor with * an incomplete object has undefined behavior (other than a special * case for visit_type_str() treating NULL like ""), while the dealloc * visitor safely handles incomplete objects. Since input visitors * never produce an incomplete object, such an object is possible only * by manual construction. * * For the QAPI object types (structs, unions, and alternates), there * is an additional generated function in qapi-visit.h compatible * with: * * void visit_type_FOO_members(Visitor *v, FOO *obj, Error **errp); * * for visiting the members of a type without also allocating the QAPI * struct. * * Additionally, in qapi-types.h, all QAPI pointer types (structs, * unions, alternates, and lists) have a generated function compatible * with: * * void qapi_free_FOO(FOO *obj); * * where behaves like free() in that @obj may be NULL. Such objects * may also be used with the following macro, provided alongside the * clone visitor: * * Type *QAPI_CLONE(Type, src); * * in order to perform a deep clone of @src. Because of the generated * qapi_free functions and the QAPI_CLONE() macro, the clone and * dealloc visitor should not be used directly outside of QAPI code. * * QAPI types can also inherit from a base class; when this happens, a * function is generated for easily going from the derived type to the * base type: * * BASE *qapi_CHILD_base(CHILD *obj); * * For a real QAPI struct, typical input usage involves: * * <example> * Foo *f; * Error *err = NULL; * Visitor *v; * * v = FOO_visitor_new(...); * visit_type_Foo(v, NULL, &f, &err); * if (err) { * ...handle error... * } else { * ...use f... * } * visit_free(v); * qapi_free_Foo(f); * </example> * * For a list, it is: * <example> * FooList *l; * Error *err = NULL; * Visitor *v; * * v = FOO_visitor_new(...); * visit_type_FooList(v, NULL, &l, &err); * if (err) { * ...handle error... * } else { * for ( ; l; l = l->next) { * ...use l->value... * } * } * visit_free(v); * qapi_free_FooList(l); * </example> * * Similarly, typical output usage is: * * <example> * Foo *f = ...obtain populated object... * Error *err = NULL; * Visitor *v; * Type *result; * * v = FOO_visitor_new(..., &result); * visit_type_Foo(v, NULL, &f, &err); * if (err) { * ...handle error... * } else { * visit_complete(v, &result); * ...use result... * } * visit_free(v); * </example> * * When visiting a real QAPI struct, this file provides several * helpers that rely on in-tree information to control the walk: * visit_optional() for the 'has_member' field associated with * optional 'member' in the C struct; and visit_next_list() for * advancing through a FooList linked list. Similarly, the * visit_is_input() helper makes it possible to write code that is * visitor-agnostic everywhere except for cleanup. Only the generated * visit_type functions need to use these helpers. * * It is also possible to use the visitors to do a virtual walk, where * no actual QAPI struct is present. In this situation, decisions * about what needs to be walked are made by the calling code, and * structured visits are split between pairs of start and end methods * (where the end method must be called if the start function * succeeded, even if an intermediate visit encounters an error). * Thus, a virtual walk corresponding to '{ "list": [1, 2] }' looks * like: * * <example> * Visitor *v; * Error *err = NULL; * int value; * * v = FOO_visitor_new(...); * visit_start_struct(v, NULL, NULL, 0, &err); * if (err) { * goto out; * } * visit_start_list(v, "list", NULL, 0, &err); * if (err) { * goto outobj; * } * value = 1; * visit_type_int(v, NULL, &value, &err); * if (err) { * goto outlist; * } * value = 2; * visit_type_int(v, NULL, &value, &err); * if (err) { * goto outlist; * } * outlist: * visit_end_list(v, NULL); * if (!err) { * visit_check_struct(v, &err); * } * outobj: * visit_end_struct(v, NULL); * out: * error_propagate(errp, err); * visit_free(v); * </example> */ /*** Useful types ***/ /* This struct is layout-compatible with all other *List structs * created by the QAPI generator. It is used as a typical * singly-linked list. */ typedef struct GenericList { struct GenericList *next; char padding[]; } GenericList; /* This struct is layout-compatible with all Alternate types * created by the QAPI generator. */ typedef struct GenericAlternate { QType type; char padding[]; } GenericAlternate; /*** Visitor cleanup ***/ /* * Complete the visit, collecting any output. * * May only be called only once after a successful top-level * visit_type_FOO() or visit_end_ITEM(), and marks the end of the * visit. The @opaque pointer should match the output parameter * passed to the subtype_visitor_new() used to create an output * visitor, or NULL for any other visitor. Needed for output * visitors, but may also be called with other visitors. */ void visit_complete(Visitor *v, void *opaque); /* * Free @v and any resources it has tied up. * * May be called whether or not the visit has been successfully * completed, but should not be called until a top-level * visit_type_FOO() or visit_start_ITEM() has been performed on the * visitor. Safe if @v is NULL. */ void visit_free(Visitor *v); /*** Visiting structures ***/ /* * Start visiting an object @obj (struct or union). * * @name expresses the relationship of this object to its parent * container; see the general description of @name above. * * @obj must be non-NULL for a real walk, in which case @size * determines how much memory an input or clone visitor will allocate * into *@obj. @obj may also be NULL for a virtual walk, in which * case @size is ignored. * * @errp obeys typical error usage, and reports failures such as a * member @name is not present, or present but not an object. On * error, input visitors set *@obj to NULL. * * After visit_start_struct() succeeds, the caller may visit its * members one after the other, passing the member's name and address * within the struct. Finally, visit_end_struct() needs to be called * with the same @obj to clean up, even if intermediate visits fail. * See the examples above. * * FIXME Should this be named visit_start_object, since it is also * used for QAPI unions, and maps to JSON objects? */ void visit_start_struct(Visitor *v, const char *name, void **obj, size_t size, Error **errp); /* * Prepare for completing an object visit. * * @errp obeys typical error usage, and reports failures such as * unparsed keys remaining in the input stream. * * Should be called prior to visit_end_struct() if all other * intermediate visit steps were successful, to allow the visitor one * last chance to report errors. May be skipped on a cleanup path, * where there is no need to check for further errors. */ void visit_check_struct(Visitor *v, Error **errp); /* * Complete an object visit started earlier. * * @obj must match what was passed to the paired visit_start_struct(). * * Must be called after any successful use of visit_start_struct(), * even if intermediate processing was skipped due to errors, to allow * the backend to release any resources. Destroying the visitor early * with visit_free() behaves as if this was implicitly called. */ void visit_end_struct(Visitor *v, void **obj); /*** Visiting lists ***/ /* * Start visiting a list. * * @name expresses the relationship of this list to its parent * container; see the general description of @name above. * * @list must be non-NULL for a real walk, in which case @size * determines how much memory an input or clone visitor will allocate * into *@list (at least sizeof(GenericList)). Some visitors also * allow @list to be NULL for a virtual walk, in which case @size is * ignored. * * @errp obeys typical error usage, and reports failures such as a * member @name is not present, or present but not a list. On error, * input visitors set *@list to NULL. * * After visit_start_list() succeeds, the caller may visit its members * one after the other. A real visit (where @obj is non-NULL) uses * visit_next_list() for traversing the linked list, while a virtual * visit (where @obj is NULL) uses other means. For each list * element, call the appropriate visit_type_FOO() with name set to * NULL and obj set to the address of the value member of the list * element. Finally, visit_end_list() needs to be called with the * same @list to clean up, even if intermediate visits fail. See the * examples above. */ void visit_start_list(Visitor *v, const char *name, GenericList **list, size_t size, Error **errp); /* * Iterate over a GenericList during a non-virtual list visit. * * @size represents the size of a linked list node (at least * sizeof(GenericList)). * * @tail must not be NULL; on the first call, @tail is the value of * *list after visit_start_list(), and on subsequent calls @tail must * be the previously returned value. Should be called in a loop until * a NULL return or error occurs; for each non-NULL return, the caller * then calls the appropriate visit_type_*() for the element type of * the list, with that function's name parameter set to NULL and obj * set to the address of @tail->value. */ GenericList *visit_next_list(Visitor *v, GenericList *tail, size_t size); /* * Complete a list visit started earlier. * * @list must match what was passed to the paired visit_start_list(). * * Must be called after any successful use of visit_start_list(), even * if intermediate processing was skipped due to errors, to allow the * backend to release any resources. Destroying the visitor early * with visit_free() behaves as if this was implicitly called. */ void visit_end_list(Visitor *v, void **list); /*** Visiting alternates ***/ /* * Start the visit of an alternate @obj. * * @name expresses the relationship of this alternate to its parent * container; see the general description of @name above. * * @obj must not be NULL. Input and clone visitors use @size to * determine how much memory to allocate into *@obj, then determine * the qtype of the next thing to be visited, stored in (*@obj)->type. * Other visitors will leave @obj unchanged. * * If @promote_int, treat integers as QTYPE_FLOAT. * * If successful, this must be paired with visit_end_alternate() with * the same @obj to clean up, even if visiting the contents of the * alternate fails. */ void visit_start_alternate(Visitor *v, const char *name, GenericAlternate **obj, size_t size, bool promote_int, Error **errp); /* * Finish visiting an alternate type. * * @obj must match what was passed to the paired visit_start_alternate(). * * Must be called after any successful use of visit_start_alternate(), * even if intermediate processing was skipped due to errors, to allow * the backend to release any resources. Destroying the visitor early * with visit_free() behaves as if this was implicitly called. * */ void visit_end_alternate(Visitor *v, void **obj); /*** Other helpers ***/ /* * Does optional struct member @name need visiting? * * @name must not be NULL. This function is only useful between * visit_start_struct() and visit_end_struct(), since only objects * have optional keys. * * @present points to the address of the optional member's has_ flag. * * Input visitors set *@present according to input; other visitors * leave it unchanged. In either case, return *@present for * convenience. */ bool visit_optional(Visitor *v, const char *name, bool *present); /* * Visit an enum value. * * @name expresses the relationship of this enum to its parent * container; see the general description of @name above. * * @obj must be non-NULL. Input visitors parse input and set *@obj to * the enumeration value, leaving @obj unchanged on error; other * visitors use *@obj but leave it unchanged. * * Currently, all input visitors parse text input, and all output * visitors produce text output. The mapping between enumeration * values and strings is done by the visitor core, using @strings; it * should be the ENUM_lookup array from visit-types.h. * * May call visit_type_str() under the hood, and the enum visit may * fail even if the corresponding string visit succeeded; this implies * that visit_type_str() must have no unwelcome side effects. */ void visit_type_enum(Visitor *v, const char *name, int *obj, const char *const strings[], Error **errp); /* * Check if visitor is an input visitor. */ bool visit_is_input(Visitor *v); /*** Visiting built-in types ***/ /* * Visit an integer value. * * @name expresses the relationship of this integer to its parent * container; see the general description of @name above. * * @obj must be non-NULL. Input visitors set *@obj to the value; * other visitors will leave *@obj unchanged. */ void visit_type_int(Visitor *v, const char *name, int64_t *obj, Error **errp); /* * Visit a uint8_t value. * Like visit_type_int(), except clamps the value to uint8_t range. */ void visit_type_uint8(Visitor *v, const char *name, uint8_t *obj, Error **errp); /* * Visit a uint16_t value. * Like visit_type_int(), except clamps the value to uint16_t range. */ void visit_type_uint16(Visitor *v, const char *name, uint16_t *obj, Error **errp); /* * Visit a uint32_t value. * Like visit_type_int(), except clamps the value to uint32_t range. */ void visit_type_uint32(Visitor *v, const char *name, uint32_t *obj, Error **errp); /* * Visit a uint64_t value. * Like visit_type_int(), except clamps the value to uint64_t range, * that is, ensures it is unsigned. */ void visit_type_uint64(Visitor *v, const char *name, uint64_t *obj, Error **errp); /* * Visit an int8_t value. * Like visit_type_int(), except clamps the value to int8_t range. */ void visit_type_int8(Visitor *v, const char *name, int8_t *obj, Error **errp); /* * Visit an int16_t value. * Like visit_type_int(), except clamps the value to int16_t range. */ void visit_type_int16(Visitor *v, const char *name, int16_t *obj, Error **errp); /* * Visit an int32_t value. * Like visit_type_int(), except clamps the value to int32_t range. */ void visit_type_int32(Visitor *v, const char *name, int32_t *obj, Error **errp); /* * Visit an int64_t value. * Identical to visit_type_int(). */ void visit_type_int64(Visitor *v, const char *name, int64_t *obj, Error **errp); /* * Visit a uint64_t value. * Like visit_type_uint64(), except that some visitors may choose to * recognize additional syntax, such as suffixes for easily scaling * values. */ void visit_type_size(Visitor *v, const char *name, uint64_t *obj, Error **errp); /* * Visit a boolean value. * * @name expresses the relationship of this boolean to its parent * container; see the general description of @name above. * * @obj must be non-NULL. Input visitors set *@obj to the value; * other visitors will leave *@obj unchanged. */ void visit_type_bool(Visitor *v, const char *name, bool *obj, Error **errp); /* * Visit a string value. * * @name expresses the relationship of this string to its parent * container; see the general description of @name above. * * @obj must be non-NULL. Input and clone visitors set *@obj to the * value (always using "" rather than NULL for an empty string). * Other visitors leave *@obj unchanged, and commonly treat NULL like * "". * * It is safe to cast away const when preparing a (const char *) value * into @obj for use by an output visitor. * * FIXME: Callers that try to output NULL *obj should not be allowed. */ void visit_type_str(Visitor *v, const char *name, char **obj, Error **errp); /* * Visit a number (i.e. double) value. * * @name expresses the relationship of this number to its parent * container; see the general description of @name above. * * @obj must be non-NULL. Input visitors set *@obj to the value; * other visitors will leave *@obj unchanged. Visitors should * document if infinity or NaN are not permitted. */ void visit_type_number(Visitor *v, const char *name, double *obj, Error **errp); /* * Visit an arbitrary value. * * @name expresses the relationship of this value to its parent * container; see the general description of @name above. * * @obj must be non-NULL. Input visitors set *@obj to the value; * other visitors will leave *@obj unchanged. *@obj must be non-NULL * for output visitors. */ void visit_type_any(Visitor *v, const char *name, QObject **obj, Error **errp); /* * Visit a JSON null value. * * @name expresses the relationship of the null value to its parent * container; see the general description of @name above. * * Unlike all other visit_type_* functions, no obj parameter is * needed; rather, this is a witness that an explicit null value is * expected rather than any other type. */ void visit_type_null(Visitor *v, const char *name, Error **errp); #endif


context:
space:
mode: