aboutsummaryrefslogtreecommitdiff
path: root/docs/devel
AgeCommit message (Collapse)Author
2018-03-12docs: document atomic_load_acquire and atomic_store_releasePaolo Bonzini
We will use them in the next patch, document what they do. Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2018-03-02qapi: Move qapi-schema.json to qapi/, rename generated filesMarkus Armbruster
Move qapi-schema.json to qapi/, so it's next to its modules, and all files get generated to qapi/, not just the ones generated for modules. Consistently name the generated files qapi-MODULE.EXT: qmp-commands.[ch] become qapi-commands.[ch], qapi-event.[ch] become qapi-events.[ch], and qmp-introspect.[ch] become qapi-introspect.[ch]. This gets rid of the temporary hacks in scripts/qapi/commands.py, scripts/qapi/events.py, and scripts/qapi/common.py. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20180211093607.27351-28-armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com> Reviewed-by: Michael Roth <mdroth@linux.vnet.ibm.com> [eblake: Fix trailing dot in tpm.c, undo temporary hack for OSX toolchain] Signed-off-by: Eric Blake <eblake@redhat.com>
2018-03-02docs: Correct outdated information on QAPIMarkus Armbruster
* Fix guidance on error classes * Point to generated documentation * Drop plea for documentation, because the QAPI code generator enforces it since commit 3313b6124b * Minor tweaks here and there Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20180211093607.27351-27-armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com> Reviewed-by: Michael Roth <mdroth@linux.vnet.ibm.com> Signed-off-by: Eric Blake <eblake@redhat.com>
2018-03-02docs/devel/writing-qmp-commands: Update for modular QAPIMarkus Armbruster
With modular code generation, putting stuff right into qapi-schema.json is a bad idea. Update writing-qmp-commands.txt accordingly. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20180211093607.27351-26-armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com> Reviewed-by: Michael Roth <mdroth@linux.vnet.ibm.com> Signed-off-by: Eric Blake <eblake@redhat.com>
2018-03-02qapi: Rename generated qmp-marshal.c to qmp-commands.cMarkus Armbruster
All generated .c are named like their .h, except for qmp-marshal.c and qmp-commands.h. To add to the confusion, tests-qmp-commands.c falsely matches generated test-qmp-commands.h. Get rid of this unnecessary complication. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20180211093607.27351-19-armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com> Reviewed-by: Michael Roth <mdroth@linux.vnet.ibm.com> Signed-off-by: Eric Blake <eblake@redhat.com>
2018-03-02qapi-gen: New common driver for code and doc generatorsMarkus Armbruster
Whenever qapi-schema.json changes, we run six programs eleven times to update eleven files. Similar for qga/qapi-schema.json. This is silly. Replace the six programs by a single program that spits out all eleven files. The programs become modules in new Python package qapi, along with the helper library. This requires moving them to scripts/qapi/. While moving them, consistently drop executable mode bits. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com> Message-Id: <20180211093607.27351-9-armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Reviewed-by: Michael Roth <mdroth@linux.vnet.ibm.com> [eblake: move change to one-line 'blurb' earlier in series, mention mode bit change as intentional, update qapi-code-gen.txt to match actual generated events.c file] Signed-off-by: Eric Blake <eblake@redhat.com>
2018-02-19docs: document our stable processCornelia Huck
Some pointers on how to get a patch into stable. [contains some suggestions by mdroth and eblake] Reviewed-by: Eric Blake <eblake@redhat.com> Reviewed-by: Michael Roth <mdroth@linux.vnet.ibm.com> Signed-off-by: Cornelia Huck <cohuck@redhat.com>
2018-02-14migration: improve documentation of postcopy-ramGreg Kurz
This capability must have the same value on both source and destination, otherwise migration fails (commit 875fcd013ab6 "migration: incoming postcopy advise sanity checks"). Let's write it down in various places where postcopy-ram is documented. Signed-off-by: Greg Kurz <groug@kaod.org> Message-Id: <151801810352.29167.4832480228518630626.stgit@bahia.lan> Signed-off-by: Dr. David Alan Gilbert <dgilbert@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Reviewed-by: Dr. David Alan Gilbert <dgilbert@redhat.com>
2018-02-09Include qapi/error.h exactly where neededMarkus Armbruster
This cleanup makes the number of objects depending on qapi/error.h drop from 1910 (out of 4743) to 1612 in my "build everything" tree. While there, separate #include from file comment with a blank line, and drop a useless comment on why qemu/osdep.h is included first. Reviewed-by: Eric Blake <eblake@redhat.com> Reviewed-by: Philippe Mathieu-Daudé <f4bug@amsat.org> Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20180201111846.21846-5-armbru@redhat.com> [Semantic conflict with commit 34e304e975 resolved, OSX breakage fixed]
2018-02-08docs: Add docs/devel/testing.rstFam Zheng
To make our efforts on QEMU testing easier to consume by contributors, let's add a document. For example, Patchew reports build errors on patches that should be relatively easy to reproduce with a few steps, and it is much nicer if there is such a documentation that it can refer to. This focuses on how to run existing tests and how to write new test cases, without going into the frameworks themselves. The VM based testing section is moved from tests/vm/README which now is a single line pointing to the new doc. Signed-off-by: Fam Zheng <famz@redhat.com> Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com> Message-Id: <20180201022046.9425-1-famz@redhat.com> Signed-off-by: Fam Zheng <famz@redhat.com>
2018-01-23migration: Revert postcopy-blocktime commit setPeter Maydell
This reverts commits ca6011c migration: add postcopy total blocktime into query-migrate 5f32dc8 migration: add blocktime calculation into migration-test 2f7dae9 migration: postcopy_blocktime documentation 3be98be migration: calculate vCPU blocktime on dst side 01a87f0 migration: add postcopy blocktime ctx into MigrationIncomingState 31bf06a migration: introduce postcopy-blocktime capability as they don't build on ppc32 due to trying to do atomic accesses on types that are larger than the host pointer type. Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
2018-01-16Merge remote-tracking branch 'remotes/bonzini/tags/for-upstream' into stagingPeter Maydell
* QemuMutex tracing improvements (Alex) * ram_addr_t optimization (David) * SCSI fixes (Fam, Stefan, me) * do {} while (0) fixes (Eric) * KVM fix for PMU (Jan) * memory leak fixes from ASAN (Marc-André) * migration fix for HPET, icount, loadvm (Maria, Pavel) * hflags fixes (me, Tao) * block/iscsi uninitialized variable (Peter L.) * full support for GMainContexts in character devices (Peter Xu) * more boot-serial-test (Thomas) * Memory leak fix (Zhecheng) # gpg: Signature made Tue 16 Jan 2018 14:15:45 GMT # gpg: using RSA key 0xBFFBD25F78C7AE83 # gpg: Good signature from "Paolo Bonzini <bonzini@gnu.org>" # gpg: aka "Paolo Bonzini <pbonzini@redhat.com>" # Primary key fingerprint: 46F5 9FBD 57D6 12E7 BFD4 E2F7 7E15 100C CD36 69B1 # Subkey fingerprint: F133 3857 4B66 2389 866C 7682 BFFB D25F 78C7 AE83 * remotes/bonzini/tags/for-upstream: (51 commits) scripts/analyse-locks-simpletrace.py: script to analyse lock times util/qemu-thread-*: add qemu_lock, locked and unlock trace events cpu: flush TB cache when loading VMState block/iscsi: fix initialization of iTask in iscsi_co_get_block_status find_ram_offset: Align ram_addr_t allocation on long boundaries find_ram_offset: Add comments and tracing cpu_physical_memory_sync_dirty_bitmap: Another alignment fix checkpatch: Enforce proper do/while (0) style maint: Fix macros with broken 'do/while(0); ' usage tests: Avoid 'do/while(false); ' in vhost-user-bridge chardev: Clean up previous patch indentation chardev: Use goto/label instead of do/break/while(0) mips: Tweak location of ';' in macros net: Drop unusual use of do { } while (0); irq: fix memory leak cpus: unify qemu_*_wait_io_event icount: fixed saving/restoring of icount warp timers scripts/qemu-gdb/timers.py: new helper to dump timer state scripts/qemu-gdb: add simple tcg lock status helper target-i386: update hflags on Hypervisor.framework ... Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
2018-01-15migration: postcopy_blocktime documentationAlexey Perevalov
Reviewed-by: Dr. David Alan Gilbert <dgilbert@redhat.com> Signed-off-by: Alexey Perevalov <a.perevalov@samsung.com> Reviewed-by: Juan Quintela <quintela@redhat.com> Signed-off-by: Juan Quintela <quintela@redhat.com>
2018-01-15docs: Convert migration.txt to rstDr. David Alan Gilbert
Mostly just manual conversion with very minor fixes. Signed-off-by: Dr. David Alan Gilbert <dgilbert@redhat.com> Reviewed-by: Daniel P. Berrange <berrange@redhat.com> Reviewed-by: Kashyap Chamarthy <kchamart@redhat.com> Reviewed-by: Peter Xu <peterx@redhat.com> Signed-off-by: Juan Quintela <quintela@redhat.com>
2018-01-12build-sys: add a rule to print a variableMarc-André Lureau
$ make print-CFLAGS CFLAGS=-fsanitize=address -Og -g Trick from various sources: https://stackoverflow.com/questions/16467718/how-to-print-out-a-variable-in-makefile https://www.cmcrossroads.com/article/printing-value-makefile-variable Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-Id: <20180104160523.22995-4-marcandre.lureau@redhat.com> Tested-by: Philippe Mathieu-Daudé <f4bug@amsat.org> Reviewed-by: Philippe Mathieu-Daudé <f4bug@amsat.org> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2017-12-20qapi-docs: fix a comment typoChen Hanxiao
s/Subection/Subsection Signed-off-by: Chen Hanxiao <chenhanxiao@gmail.com> Message-Id: <20171012064448.20276-1-chen_han_xiao@126.com> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
2017-12-19docs: mark nested AioContext locking as a legacy APIStefan Hajnoczi
See the patch for why nested AioContext locking is no longer allowed. Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-id: 20171207201320.19284-3-stefanha@redhat.com Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
2017-10-16docs/devel/loads-stores.rst: Document our various load and store APIsPeter Maydell
QEMU has a wide selection of different functions for doing loads and stores; provide some overview documentation of what they do and how to pick which one to use. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Eric Blake <eblake@redhat.com> Message-Id: <1507813181-11860-1-git-send-email-peter.maydell@linaro.org> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2017-09-27migration: pre_save return intDr. David Alan Gilbert
Modify the pre_save method on VMStateDescription to return an int rather than void so that it potentially can fail. Changed zillions of devices to make them return 0; the only case I've made it return non-0 is hw/intc/s390_flic_kvm.c that already had an error_report/return case. Note: If you add an error exit in your pre_save you must emit an error_report to say why. Signed-off-by: Dr. David Alan Gilbert <dgilbert@redhat.com> Message-Id: <20170925112917.21340-2-dgilbert@redhat.com> Reviewed-by: Peter Xu <peterx@redhat.com> Reviewed-by: Cornelia Huck <cohuck@redhat.com> Reviewed-by: Juan Quintela <quintela@redhat.com> Signed-off-by: Dr. David Alan Gilbert <dgilbert@redhat.com>
2017-09-21memory: avoid "resurrection" of dead FlatViewsPaolo Bonzini
It's possible for address_space_get_flatview() as it currently stands to cause a use-after-free for the returned FlatView, if the reference count is incremented after the FlatView has been replaced by a writer: thread 1 thread 2 RCU thread ------------------------------------------------------------- rcu_read_lock read as->current_map set as->current_map flatview_unref '--> call_rcu flatview_ref [ref=1] rcu_read_unlock flatview_destroy <badness> Since FlatViews are not updated very often, we can just detect the situation using a new atomic op atomic_fetch_inc_nonzero, similar to Linux's atomic_inc_not_zero, which performs the refcount increment only if it hasn't already hit zero. This is similar to Linux commit de09a9771a53 ("CRED: Fix get_task_cred() and task_state() to not resurrect dead credentials", 2010-07-29). Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2017-09-21atomic: update documentationPaolo Bonzini
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2017-09-19Makefile: Remove libqemustub.aPaolo Bonzini
Using two libraries (libqemuutil.a and libqemustub.a) would sometimes result in circular dependencies. To avoid these issues let's just combine both into a single library that functions as both. Signed-off-by: Alistair Francis <alistair.francis@xilinx.com> Message-Id: <54e6458745493d10901964624479a7d9a872f481.1503077821.git.alistair.francis@xilinx.com> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2017-09-04qapi: Generate FOO_str() macro for QAPI enum FOOMarkus Armbruster
The next commit will put it to use. May look pointless now, but we're going to change the FOO_lookup's type, and then it'll help. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <1503564371-26090-13-git-send-email-armbru@redhat.com> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
2017-09-04qapi: Update qapi-code-gen.txt examples to match current codeMarkus Armbruster
Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <1503564371-26090-2-git-send-email-armbru@redhat.com> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
2017-08-01trace: add trace_event_get_state_backends()Stefan Hajnoczi
Code that checks dstate is unaware of SystemTap and LTTng UST dstate, so the following trace event will not fire when solely enabled by SystemTap or LTTng UST: if (trace_event_get_state(TRACE_MY_EVENT)) { str = g_strdup_printf("Expensive string to generate ...", ...); trace_my_event(str); g_free(str); } Add trace_event_get_state_backends() to fetch backend dstate. Those backends that use QEMU dstate fetch it as part of generate_h_backend_dstate(). Update existing trace_event_get_state() callers to use trace_event_get_state_backends() instead. Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com> Message-id: 20170731140718.22010-3-stefanha@redhat.com Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
2017-07-31docs: fix broken paths to docs/devel/atomics.txtPhilippe Mathieu-Daudé
With the move of some docs/ to docs/devel/ on ac06724a71, a couple of references were not updated. Signed-off-by: Philippe Mathieu-Daudé <f4bug@amsat.org> Signed-off-by: Michael Tokarev <mjt@tls.msk.ru>
2017-07-31docs: fix broken paths to docs/devel/qapi-code-gen.txtPhilippe Mathieu-Daudé
With the move of some docs to docs/interop on ac06724a71, a couple of references were not updated. Signed-off-by: Philippe Mathieu-Daudé <f4bug@amsat.org> Signed-off-by: Michael Tokarev <mjt@tls.msk.ru>
2017-07-31docs: fix broken paths to docs/interop dirCleber Rosa
With the move of some docs to docs/interop on d59157e, a couple of references were not updated. Signed-off-by: Cleber Rosa <crosa@redhat.com> [PMD: fixed a typo and another reference of docs/interop/qmp-spec.txt] Signed-off-by: Philippe Mathieu-Daudé <f4bug@amsat.org> Reviewed-by: Eric Blake <eblake@redhat.com> Signed-off-by: Michael Tokarev <mjt@tls.msk.ru>
2017-07-24qapi: Introduce a first class 'null' typeMarkus Armbruster
I expect the 'null' type to be useful mostly for members of alternate types. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Daniel P. Berrange <berrange@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
2017-07-18Merge remote-tracking branch 'remotes/cody/tags/block-pull-request' into stagingPeter Maydell
# gpg: Signature made Tue 18 Jul 2017 05:15:03 BST # gpg: using RSA key 0xBDBE7B27C0DE3057 # gpg: Good signature from "Jeffrey Cody <jcody@redhat.com>" # gpg: aka "Jeffrey Cody <jeff@codyprime.org>" # gpg: aka "Jeffrey Cody <codyprime@gmail.com>" # Primary key fingerprint: 9957 4B4D 3474 90E7 9D98 D624 BDBE 7B27 C0DE 3057 * remotes/cody/tags/block-pull-request: live-block-ops.txt: Rename, rewrite, and improve it bitmaps.md: Convert to rST; move it into 'interop' dir Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
2017-07-18bitmaps.md: Convert to rST; move it into 'interop' dirKashyap Chamarthy
This is part of the on-going effort to convert QEMU upstream documentation syntax to reStructuredText (rST). The conversion to rST was done using: $ pandoc -f markdown -t rst bitmaps.md -o bitmaps.rst Then, make a couple of small syntactical adjustments. While at it, reword a statement to avoid ambiguity. Addressing the feedback from this thread: https://lists.nongnu.org/archive/html/qemu-devel/2017-06/msg05428.html Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com> Reviewed-by: John Snow <jsnow@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-id: 20170717105205.32639-2-kchamart@redhat.com Signed-off-by: Jeff Cody <jcody@redhat.com>
2017-07-17Merge remote-tracking branch 'remotes/stefanha/tags/tracing-pull-request' ↵Peter Maydell
into staging # gpg: Signature made Mon 17 Jul 2017 13:11:17 BST # gpg: using RSA key 0x9CA4ABB381AB73C8 # gpg: Good signature from "Stefan Hajnoczi <stefanha@redhat.com>" # gpg: aka "Stefan Hajnoczi <stefanha@gmail.com>" # Primary key fingerprint: 8695 A8BF D3F9 7CDA AC35 775A 9CA4 ABB3 81AB 73C8 * remotes/stefanha/tags/tracing-pull-request: trace: update old trace events in docs trace: [trivial] Statically enable all guest events trace: [tcg, trivial] Re-align generated code trace: [tcg] Do not generate TCG code to trace dynamically-disabled events exec: [tcg] Use different TBs according to the vCPU's dynamic tracing state trace: [tcg] Delay changes to dynamic state when translating trace: Allocate cpu->trace_dstate in place Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
2017-07-17trace: update old trace events in docsStefan Hajnoczi
Commit c5f1ad429cdf26023cf331075a7d327708e3db6d ("block: Remove bdrv_aio_readv/writev/flush()") removed bdrv_aio_readv()/bdrv_aio_writev() so the example in the tracing documentation is no longer valid. Reported-by: Wang Dong <dongdwdw@linux.vnet.ibm.com> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-id: 20170714133111.27359-1-stefanha@redhat.com Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
2017-07-14docs/devel/memory.txt: Add section about RAM migrationPeter Maydell
Add a section to docs/devel/memory.txt about migration of the backing memory for RAM regions. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Paolo Bonzini <pbonzini@redhat.com> Message-id: 1499438577-7674-12-git-send-email-peter.maydell@linaro.org
2017-06-07docs: create config/, devel/ and spin/ subdirectoriesPaolo Bonzini
Developer documentation should be its own manual. As a start, move all developer-oriented files to a separate directory. Also move non-text files to their own directories: docs/config/ for QEMU -readconfig input, and docs/spin/ for formal models to be used with the SPIN model checker. Reviewed-by: Daniel P. Berrange <berrange@redhat.com> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>