aboutsummaryrefslogtreecommitdiff
path: root/scripts
AgeCommit message (Collapse)Author
2015-09-14qapi: Fix cgen() for Python older than 2.7Markus Armbruster
A feature new in Python 2.7 crept into commit 77e703b: re.subn()'s fifth argument. Avoid that, use re.compile(). Reported-by: Laurent Desnogues <laurent.desnogues@gmail.com> Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Tested-by: Laurent Desnogues <laurent.desnogues@gmail.com> Message-id: 1441640755-23902-1-git-send-email-armbru@redhat.com Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
2015-09-14Merge remote-tracking branch 'remotes/bonzini/tags/for-upstream' into stagingPeter Maydell
* Support for jemalloc * qemu_mutex_lock_iothread "No such process" fix * cutils: qemu_strto* wrappers * iohandler.c simplification * Many other fixes and misc patches. And some MTTCG work (with Emilio's fixes squashed): * Signal-free TCG kick * Removing spinlock in favor of QemuMutex * User-mode emulation multi-threading fixes/docs # gpg: Signature made Thu 10 Sep 2015 09:03:07 BST using RSA key ID 78C7AE83 # gpg: Good signature from "Paolo Bonzini <bonzini@gnu.org>" # gpg: aka "Paolo Bonzini <pbonzini@redhat.com>" * remotes/bonzini/tags/for-upstream: (44 commits) cutils: work around platform differences in strto{l,ul,ll,ull} cpu-exec: fix lock hierarchy for user-mode emulation exec: make mmap_lock/mmap_unlock globally available tcg: comment on which functions have to be called with mmap_lock held tcg: add memory barriers in page_find_alloc accesses remove unused spinlock. replace spinlock by QemuMutex. cpus: remove tcg_halt_cond and tcg_cpu_thread globals cpus: protect work list with work_mutex scripts/dump-guest-memory.py: fix after RAMBlock change configure: Add support for jemalloc add macro file for coccinelle configure: factor out adding disas configure vhost-scsi: fix wrong vhost-scsi firmware path checkpatch: remove tests that are not relevant outside the kernel checkpatch: adapt some tests to QEMU CODING_STYLE: update mixed declaration rules qmp: Add example usage of strto*l() qemu wrapper cutils: Add qemu_strtoull() wrapper cutils: Add qemu_strtoll() wrapper ... Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
2015-09-11scripts/qemu-gdb: Add brief comment describing usagePeter Maydell
Add a brief comment describing how to use the debug support from GDB. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com> Message-id: 1439574392-4403-5-git-send-email-peter.maydell@linaro.org
2015-09-11scripts/qemu-gdb: Silently pass through SIGUSR1Peter Maydell
SIGUSR1 is QEMU's IPI signal, and it gets sent a lot, so is best silently passed through to the guest without stopping. Make qemu-gdb.py do this bit of configuration for the user. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com> Message-id: 1439574392-4403-4-git-send-email-peter.maydell@linaro.org
2015-09-11scripts/qemu-gdb: Split CoroutineCommand into its own filePeter Maydell
Split the implementation of CoroutineCommand into its own file. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com> Message-id: 1439574392-4403-3-git-send-email-peter.maydell@linaro.org
2015-09-11scripts/qemu-gdb: Split MtreeCommand into its own modulePeter Maydell
As we add more commands to our Python gdb debugging support, it's going to get unwieldy to have everything in a single file. Split the implementation of the 'mtree' command from qemu-gdb.py into its own module. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com> Message-id: 1439574392-4403-2-git-send-email-peter.maydell@linaro.org
2015-09-09scripts/dump-guest-memory.py: fix after RAMBlock changeMichael S. Tsirkin
commit 9b8424d5735278ca382f11adc7c63072b632ab83 "exec: split length -> used_length/max_length" changed field names in struct RAMBlock It turns out that scripts/dump-guest-memory.py was poking at this field, update it accordingly. Cc: qemu-stable@nongnu.org Cc: Paolo Bonzini <pbonzini@redhat.com> Signed-off-by: Michael S. Tsirkin <mst@redhat.com> Message-Id: <1440666378-3152-1-git-send-email-mst@redhat.com> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2015-09-09add macro file for coccinellePaolo Bonzini
Coccinelle chokes on some idioms from compiler.h and queue.h. Extract those in a macro file, to be used with "--macro-file scripts/cocci-macro-file.h". Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2015-09-09checkpatch: remove tests that are not relevant outside the kernelPaolo Bonzini
Fully removing Sparse support requires more invasive changes. Only remove the really kernel-specific parts such as address space names. Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2015-09-09checkpatch: adapt some tests to QEMUPaolo Bonzini
Mostly change severity levels, but some tests can also be adjusted to refer to QEMU APIs or data structures. Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2015-09-04Merge remote-tracking branch 'remotes/armbru/tags/pull-monitor-2015-09-04' ↵Peter Maydell
into staging Monitor patches # gpg: Signature made Fri 04 Sep 2015 12:40:11 BST using RSA key ID EB918653 # gpg: Good signature from "Markus Armbruster <armbru@redhat.com>" # gpg: aka "Markus Armbruster <armbru@pond.sub.org>" * remotes/armbru/tags/pull-monitor-2015-09-04: hmp: add info iothreads command qmp-shell: add documentation Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
2015-09-04qapi: Generators crash when --output-dir isn't given, fixMarkus Armbruster
Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
2015-09-04qapi: Simplify error reporting for array typesMarkus Armbruster
check_type() first checks and peels off the array type, then checks the element type. For two out of four error messages, it takes pains to report errors for "array of T" instead of just T. Odd. Let's examine the errors. * Unknown element type, e.g. tests/qapi-schema/args-array-unknown.json: Member 'array' of 'data' for command 'oops' uses unknown type 'array of NoSuchType' To make sense of this, you need to know that 'array of NoSuchType' refers to '[NoSuchType]'. Easy enough. However, simply reporting Member 'array' of 'data' for command 'oops' uses unknown type 'NoSuchType' is at least as easy to understand. * Element type's meta-type is inadmissible, e.g. tests/qapi-schema/returns-whitelist.json: 'returns' for command 'no-way-this-will-get-whitelisted' cannot use built-in type 'array of int' 'array of int' is technically not a built-in type, but that's pedantry. However, simply reporting 'returns' for command 'no-way-this-will-get-whitelisted' cannot use built-in type 'int' avoids the issue, and is at least as easy to understand. * The remaining two errors are unreachable, because the array checking ensures that value is a string. Thus, reporting some errors for "array of T" instead of just T works, but doesn't really improve things. Drop it. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
2015-09-04qapi: Fix errors for non-string, non-dictionary membersMarkus Armbruster
Fixes the errors demonstrated by the previous commit. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
2015-09-04qapi: Drop one of two "simple union must not have base" checksMarkus Armbruster
The first check ensures the second one can't trigger. Drop the first one, because the second one is in a more logical place, and emits a nicer error message. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
2015-09-04qapi: Generated code cleanupMarkus Armbruster
Clean up white-space, brace placement, and superfluous #ifdef QAPI_TYPES_BUILTIN_CLEANUP_DEF. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
2015-09-04qapi-commands: Drop useless initializationMarkus Armbruster
In generated command handlers, the assignment to retval dominates its only use. Therefore, its initialization is useless. Drop it. Suggested-by: Eric Blake <eblake@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
2015-09-04qapi-commands: Don't feed output of mcgen() to mcgen() againMarkus Armbruster
Multiple passes through mcgen() is prone to produce unwanted blank lines, which we then combat by sprinkling .rstrip() on top. Just don't do it. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
2015-09-04qapi-commands: Inline gen_marshal_output_call()Markus Armbruster
Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
2015-09-04qapi-commands: Fix gen_err_check(e) for e and e != 'local_err'Markus Armbruster
gen_err_check() hard-codes 'local_err' instead of substituting the argument. Currently harmless, since all callers pass either None or 'local_err'. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
2015-09-04qapi: Command returning anonymous type doesn't work, outlawMarkus Armbruster
Reproducer: with { 'command': 'user_def_cmd4', 'returns': { 'a': 'int' } } added to qapi-schema-test.json, qapi-commands.py dies when it tries to generate the command handler function Traceback (most recent call last): File "/work/armbru/qemu/scripts/qapi-commands.py", line 359, in <module> ret = generate_command_decl(cmd['command'], arglist, ret_type) + "\n" File "/work/armbru/qemu/scripts/qapi-commands.py", line 29, in generate_command_decl ret_type=c_type(ret_type), name=c_name(name), File "/work/armbru/qemu/scripts/qapi.py", line 927, in c_type assert isinstance(value, str) and value != "" AssertionError because the return type doesn't exist. Simply outlaw this usage, and drop or dumb down test cases accordingly. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
2015-09-04qapi: Fix to reject union command and event argumentsMarkus Armbruster
A command's or event's 'data' must be a struct type, given either as a dictionary, or as struct type name. Commit dd883c6 tightened the checking there, but not enough: we still accept 'union'. Fix to reject it. We may want to support union types there, but we'll have to extend qapi-commands.py and qapi-events.py for it. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
2015-09-04qapi: Document flaws in checking of namesMarkus Armbruster
We don't actually enforce our "other than downstream extensions [...], all names should begin with a letter" rule. Add a FIXME. We should reject names that differ only in '_' vs. '.' vs. '-', because they're liable to clash in generated C. Add a FIXME. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
2015-09-04qapi: Document shortcoming with union 'data' branchEric Blake
Add a FIXME to remind us to fully audit whether removing the 'void *data' branch of each qapi union type can be done safely. Signed-off-by: Eric Blake <eblake@redhat.com> Message-Id: <1438297637-26789-1-git-send-email-eblake@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
2015-09-04qapi: Document that input visitor semantics are prone to leaksEric Blake
Most functions that can return a pointer or set an Error ** value are decent enough to guarantee a NULL return when reporting an error. Not so with our generated qapi visitor functions. If the caller is not careful to clean up partially-allocated objects on error, then the caller suffers a memory leak. Properly fixing it is probably complex enough to save for a later day, so merely document it for now. Signed-off-by: Eric Blake <eblake@redhat.com> Message-Id: <1438295587-19069-1-git-send-email-eblake@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
2015-09-04qapi-visit: Fix two name arguments passed to visitorsMarkus Armbruster
The generated code passes mangled schema names to visit_type_enum() and union's visit_start_struct(). Fix it to pass the names unadulterated, like we do everywhere else. Only qapi-schema-test.json actually has names where this makes a difference: enum __org.qemu_x-Enum, flat union __org.qemu_x-Union2, simple union __org.qemu_x-Union1 and its implicit enum __org.qemu_x-Union1Kind. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
2015-09-04qapi-visit: Replace list implicit_structs by setMarkus Armbruster
Use set because that's what it is. While there, rename to implicit_structs_seen. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
2015-09-04qapi-visit: Fix generated code when schema has forward refsMarkus Armbruster
The visit_type_implicit_FOO() are generated on demand, right before their first use. Used by visit_type_STRUCT_fields() when STRUCT has base FOO, and by visit_type_UNION() when flat UNION has member a FOO. If the schema defines FOO after its first use as struct base or flat union member, visit_type_implicit_FOO() calls visit_type_implicit_FOO() before its definition, which doesn't compile. Rearrange qapi-schema-test.json to demonstrate the bug. Fix by generating the necessary forward declaration. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
2015-09-04qapi: Generate a nicer struct for flat unionsMarkus Armbruster
The struct generated for a flat union is weird: the members of its base are at the end, except for the union tag, which is at the beginning. Example: qapi-schema-test.json has { 'struct': 'UserDefUnionBase', 'data': { 'string': 'str', 'enum1': 'EnumOne' } } { 'union': 'UserDefFlatUnion', 'base': 'UserDefUnionBase', 'discriminator': 'enum1', 'data': { 'value1' : 'UserDefA', 'value2' : 'UserDefB', 'value3' : 'UserDefB' } } We generate: struct UserDefFlatUnion { EnumOne enum1; union { void *data; UserDefA *value1; UserDefB *value2; UserDefB *value3; }; char *string; }; Change to put all base members at the beginning, unadulterated. Not only is this easier to understand, it also permits casting the flat union to its base, if that should become useful. We now generate: struct UserDefFlatUnion { /* Members inherited from UserDefUnionBase: */ char *string; EnumOne enum1; /* Own members: */ union { /* union tag is @enum1 */ void *data; UserDefA *value1; UserDefB *value2; UserDefB *value3; }; }; Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
2015-09-04qapi: Fix generated code when flat union has member 'kind'Markus Armbruster
A flat union's tag member gets renamed to 'kind' in the generated code. Breaks when another member named 'kind' exists. Example, adapted from qapi-schema-test.json: { 'struct': 'UserDefUnionBase', 'data': { 'kind': 'str', 'enum1': 'EnumOne' } } We generate: struct UserDefFlatUnion { EnumOne kind; union { void *data; UserDefA *value1; UserDefB *value2; UserDefB *value3; }; char *kind; }; Kill the silly rename. Reported-by: Eric Blake <eblake@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
2015-09-04qapi: Drop unused and useless parameters and variablesMarkus Armbruster
gen_sync_call()'s parameter indent is useless: gen_sync_call() uses it only as optional argument for push_indent() and pop_indent(), their default is four, and gen_sync_call()'s only caller passes four. Drop the parameter. gen_visitor_input_containers_decl()'s parameter obj is always "QOBJECT(args)". Use that, and drop the parameter. Drop unused parameters of gen_marshal_output(), gen_marshal_input_decl(), generate_visit_struct_body(), generate_visit_list(), generate_visit_enum(), generate_declaration(), generate_enum_declaration(), generate_decl_enum(). Drop unused variables in generate_event_enum_lookup(), generate_enum_lookup(), generate_visit_struct_fields(), check_event(). Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
2015-09-04qapi: Reject -p arguments that break qapi-event.pyMarkus Armbruster
qapi-event.py breaks when you ask for a funny prefix like '@'. Protect it. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
2015-09-04qapi-event: Clean up how name of enum QAPIEvent is madeMarkus Armbruster
Use c_name() instead of ad hoc code. Doesn't upcase the -p prefix, which is an improvement in my book. Unbreaks prefix containing '.', but other funny characters remain broken. To be fixed next. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
2015-09-04qapi: Simplify guardname()Markus Armbruster
The guards around built-in declarations lose their _H. It never made much sense anyway. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
2015-09-04qapi: Clean up cgen() and mcgen()Markus Armbruster
Commit 05dfb26 added eatspace stripping to mcgen(). Move it to cgen(), just in case somebody gets tempted to use cgen() directly instead of via mcgen(). cgen() indents blank lines. No such lines get generated right now, but fix it anyway. We use triple-quoted strings for program text, like this: ''' Program text any number of lines ''' Keeps the program text relatively readable, but puts an extra newline at either end. mcgen() "fixes" that by dropping the first and last line outright. Drop only the newlines. This unmasks a bug in qapi-commands.py: four quotes instead of three. Fix it up. Output doesn't change Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
2015-09-04qmp-shell: add documentationJohn Snow
I should probably document the changes that were made. Signed-off-by: John Snow <jsnow@redhat.com> Message-Id: <1435775149-17285-1-git-send-email-jsnow@redhat.com> Reviewed-By: Kashyap Chamarthy <kchamart@redhat.com> Reviewed-by: Luiz Capitulino <lcapitulino@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
2015-07-16virtio-input: move sys/ioctl.h includeGerd Hoffmann
Drop from include/standard-headers/linux/input.h Add to hw/input/virtio-input-host.c instead. That allows to build virtio-input (except pass-through) on windows. Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
2015-07-08pci_regs.h: import from linuxMichael S. Tsirkin
It seems to make sense to import pci_regs.h from linux: why maintain our own? As a first step, move the header to standard-headers, and add it to the update script. Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
2015-06-22Include qapi/qmp/qerror.h exactly where neededMarkus Armbruster
In particular, don't include it into headers. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Reviewed-by: Luiz Capitulino <lcapitulino@redhat.com>
2015-06-22qmp: Wean off qerror_report()Markus Armbruster
The traditional QMP command handler interface int qmp_FOO(Monitor *mon, const QDict *params, QObject **ret_data); doesn't provide for returning an Error object. Instead, the handler is expected to stash it in the monitor with qerror_report(). When we rebased QMP on top of QAPI, we didn't change this interface. Instead, commit 776574d introduced "middle mode" as a temporary aid for converting existing QMP commands to QAPI one by one. More than three years later, we're still using it. Middle mode has two effects: * Instead of the native input marshallers static void qmp_marshal_input_FOO(QDict *, QObject **, Error **) it generates input marshallers conforming to the traditional QMP command handler interface. * It suppresses generation of code to register them with qmp_register_command() This permits giving them internal linkage. As long as we need qmp-commands.hx, we can't use the registry behind qmp_register_command(), so the latter has to stay for now. The former has to go to get rid of qerror_report(). Changing all QMP commands to fit the QAPI mold in one go was impractical back when we started, but by now there are just a few stragglers left: do_qmp_capabilities(), qmp_qom_set(), qmp_qom_get(), qmp_object_add(), qmp_netdev_add(), do_device_add(). Switch middle mode to generate native input marshallers, and adapt the stragglers. Simplifies both the monitor code and the stragglers. Rename do_qmp_capabilities() to qmp_capabilities(), and do_device_add() to qmp_device_add, because that's how QMP command handlers are named today. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Reviewed-by: Luiz Capitulino <lcapitulino@redhat.com>
2015-06-19qom: Make enum string tables const-correctDaniel P. Berrange
The enum string table parameters in various QOM/QAPI methods are declared 'const char *strings[]'. This results in const warnings if passed a variable that was declared as static const char * const strings[] = { .... }; Add the extra const annotation to the parameters, since neither the string elements, nor the array itself should ever be modified. Signed-off-by: Daniel P. Berrange <berrange@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Signed-off-by: Andreas Färber <afaerber@suse.de>
2015-06-19scripts: Add support for path as argument of qom-treeMartin Cerveny
Add processing of optional argument path as "tree base". Signed-off-by: Martin Cerveny <M.Cerveny@computer.org> Signed-off-by: Andreas Färber <afaerber@suse.de>
2015-06-18qapi-types: Bury code dead since commit 6b5abc7Markus Armbruster
Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
2015-06-18qapi-types: Split generate_fwd_builtin() off generate_fwd_struct()Markus Armbruster
Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
2015-06-18qapi-types: Drop unused members parametersMarkus Armbruster
Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
2015-06-18qapi-types: Don't filter out expressions with 'gen'Markus Armbruster
Useless, because it can only occur in commands, and we're not dealing with commands here. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
2015-06-18qapi: Catch and reject flat union branch of array typeMarkus Armbruster
Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
2015-06-18qapi: Better separate the different kinds of helpersMarkus Armbruster
Insert comments to separate sections dealing with parsing, semantic analysis, code generation, and so forth. Move helpers to their proper section. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
2015-06-18qapi: Move exprs checking from parse_schema() to check_exprs()Markus Armbruster
To have expression semantic analysis in one place rather than two. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
2015-06-18qapi: Fix to reject stray 't', 'f' and 'n'Markus Armbruster
Screwed up in commit e53188a. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>