mirrors/qemu
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
a975a24aed
qemu/tests
History
Marc-André Lureau 3313b6124b qapi: add qapi2texi script 
As the name suggests, the qapi2texi script converts JSON QAPI
description into a texi file suitable for different target
formats (info/man/txt/pdf/html...).

It parses the following kind of blocks:

Free-form:

  ##
  # = Section
  # == Subsection
  #
  # Some text foo with *emphasis*
  # 1. with a list
  # 2. like that
  #
  # And some code:
  # | $ echo foo
  # | -> do this
  # | <- get that
  #
  ##

Symbol description:

  ##
  # @symbol:
  #
  # Symbol body ditto ergo sum. Foo bar
  # baz ding.
  #
  # @param1: the frob to frobnicate
  # @param2: #optional how hard to frobnicate
  #
  # Returns: the frobnicated frob.
  #          If frob isn't frobnicatable, GenericError.
  #
  # Since: version
  # Notes: notes, comments can have
  #        - itemized list
  #        - like this
  #
  # Example:
  #
  # -> { "execute": "quit" }
  # <- { "return": {} }
  #
  ##

That's roughly following the following EBNF grammar:

api_comment = "##\n" comment "##\n"
comment = freeform_comment | symbol_comment
freeform_comment = { "# " text "\n" | "#\n" }
symbol_comment = "# @" name ":\n" { member | tag_section | freeform_comment }
member = "# @" name ':' [ text ] "\n" freeform_comment
tag_section = "# " ( "Returns:", "Since:", "Note:", "Notes:", "Example:", "Examples:" ) [ text ]  "\n" freeform_comment
text = free text with markup

Note that the grammar is ambiguous: a line "# @foo:\n" can be parsed
both as freeform_comment and as symbol_comment.  The actual parser
recognizes symbol_comment.

See docs/qapi-code-gen.txt for more details.

Deficiencies and limitations:
- the generated QMP documentation includes internal types
- union type support is lacking
- type information is lacking in generated documentation
- doc comment error message positions are imprecise, they point
  to the beginning of the comment.
- a few minor issues, all marked TODO/FIXME in the code

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Message-Id: <20170113144135.5150-16-marcandre.lureau@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[test-qapi.py tweaked to avoid trailing empty lines in .out]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
2017-01-16 10:10:35 +01:00
..
acpi-test-data acpi-test: update expected files 2017-01-10 07:06:42 +02:00
data tests: use static qga config file 2016-07-25 13:23:18 -05:00
docker tests/docker/Makefile.include: add a generic docker-run target 2016-10-17 10:05:48 +08:00
guest-debug tests/guest-debug: introduce basic gdbstub tests 2015-12-17 13:37:15 +00:00
image-fuzzer tests: Use Python 2.6 "except E as ..." syntax 2016-02-08 17:29:54 +01:00
libqos libqos/ahci: Add get_sense and test_ready 2016-11-14 11:15:55 -05:00
migration tests: introduce a framework for testing migration performance 2016-07-22 13:23:39 +05:30
multiboot tests/multiboot: Add test for modules 2015-01-26 12:22:44 +01:00
qapi-schema qapi: add qapi2texi script 2017-01-16 10:10:35 +01:00
qemu-iotests blkverify: Implement bdrv_co_preadv/pwritev/flush 2017-01-09 13:30:52 +01:00
rocker rocker: tests: don't need to specify master/self when setting vlans 2015-07-07 13:13:22 +01:00
tcg Move target-* CPU file into a target/ folder 2016-12-20 21:52:12 +01:00
vmstate-static-checker-data
.gitignore tests: New test-bitcnt 2017-01-10 08:49:59 -08:00
ac97-test.c tests: Remove unnecessary glib.h includes 2016-06-07 18:19:24 +03:00
ahci-test.c ahci-test: add QMP tray test for ATAPI 2016-11-14 11:15:55 -05:00
atomic_add-bench.c tests: add atomic_add-bench 2016-10-26 08:29:01 -07:00
bios-tables-test.c tests: pc: add memory hotplug acpi tables tests 2017-01-10 07:02:53 +02:00
boot-order-test.c tests: Remove unnecessary glib.h includes 2016-06-07 18:19:24 +03:00
boot-sector.c tests/boot-sector: Increase time-out to 90 seconds 2016-10-14 10:06:47 +11:00
boot-sector.h tests/boot-sector: Use mkstemp() to create a unique file name 2016-10-14 10:06:47 +11:00
boot-serial-test.c boot-serial-test: Add a test for the powernv machine 2016-11-15 11:45:01 +11:00
check-block.sh tests: allow to specify list of formats to test for check-block.sh 2016-09-23 13:36:09 +02:00
check-qdict.c qdict: implement a qdict_crumple method for un-flattening a dict 2016-10-25 17:56:14 +02:00
check-qfloat.c tests: Remove unnecessary glib.h includes 2016-06-07 18:19:24 +03:00
check-qint.c tests: Remove unnecessary glib.h includes 2016-06-07 18:19:24 +03:00
check-qjson.c tests: Avoid qobject_from_jsonf("%"PRId64) 2016-12-05 17:09:34 +01:00
check-qlist.c tests: Remove unnecessary glib.h includes 2016-06-07 18:19:24 +03:00
check-qnull.c qapi: rename QmpOutputVisitor to QObjectOutputVisitor 2016-10-25 16:25:54 +02:00
check-qom-interface.c tests: fix check-qom-interface leaks 2016-09-08 17:57:32 +04:00
check-qom-proplist.c tests: fix check-qom-proplist leaks 2016-09-08 17:57:32 +04:00
check-qstring.c tests: Remove unnecessary glib.h includes 2016-06-07 18:19:24 +03:00
crypto-tls-x509-helpers.c tests: Clean up includes 2016-02-16 14:29:27 +00:00
crypto-tls-x509-helpers.h clean-up: removed duplicate #includes 2016-10-28 18:17:24 +03:00
device-introspect-test.c tests: Remove unnecessary glib.h includes 2016-06-07 18:19:24 +03:00
display-vga-test.c coccinelle: Remove unnecessary variables for function return value 2016-06-20 16:38:13 +02:00
drive_del-test.c tests: add drive_del-test to ppc/ppc64 2016-07-29 14:14:15 +10:00
ds1338-test.c tests: Remove unnecessary glib.h includes 2016-06-07 18:19:24 +03:00
e1000-test.c tests: Remove unnecessary glib.h includes 2016-06-07 18:19:24 +03:00
e1000e-test.c libqos: Change PCI accessors to take opaque BAR handle 2016-10-28 09:38:27 +11:00
eepro100-test.c tests: Remove unnecessary glib.h includes 2016-06-07 18:19:24 +03:00
endianness-test.c spapr: Improved placement of PCI host bridges in guest memory map 2016-10-16 12:04:15 +11:00
es1370-test.c tests: Remove unnecessary glib.h includes 2016-06-07 18:19:24 +03:00
fdc-test.c tests: Remove unnecessary glib.h includes 2016-06-07 18:19:24 +03:00
fw_cfg-test.c tests: Remove unnecessary glib.h includes 2016-06-07 18:19:24 +03:00
hd-geo-test.c tests/hd-geo-test: Don't pass NULL to unlink() 2016-09-08 10:43:58 +01:00
i440fx-test.c libqos: add PCI management in qtest_vboot()/qtest_shutdown() 2016-10-06 16:15:53 +11:00
i82801b11-test.c tests: Remove unnecessary glib.h includes 2016-06-07 18:19:24 +03:00
ide-test.c tests: Remove unneeded "-vnc none" option 2016-10-31 15:09:59 -02:00
intel-hda-test.c coccinelle: Remove unnecessary variables for function return value 2016-06-20 16:38:13 +02:00
io-channel-helpers.c include/qemu/osdep.h: Don't include qapi/error.h 2016-03-22 22:20:15 +01:00
io-channel-helpers.h io: add QIOChannelSocket class 2015-12-18 12:18:31 +00:00
ioh3420-test.c tests: Remove unnecessary glib.h includes 2016-06-07 18:19:24 +03:00
ipmi-bt-test.c virtio, pc: fixes and features 2016-11-03 14:41:53 +00:00
ipmi-kcs-test.c tests: Remove unneeded "-vnc none" option 2016-10-31 15:09:59 -02:00
ipoctal232-test.c tests: Remove unnecessary glib.h includes 2016-06-07 18:19:24 +03:00
ivshmem-test.c libqos: Change PCI accessors to take opaque BAR handle 2016-10-28 09:38:27 +11:00
libqtest.c libqtest: handle zero length memwrite/memread 2017-01-12 10:45:59 +00:00
libqtest.h libqtest: add qmp_eventwait_ref 2016-11-14 11:15:54 -05:00
m25p80-test.c tests: add a m25p80 test 2016-10-17 19:22:17 +01:00
m48t59-test.c tests: Remove unnecessary glib.h includes 2016-06-07 18:19:24 +03:00
Makefile.include qapi: add qapi2texi script 2017-01-16 10:10:35 +01:00
ne2000-test.c tests: Remove unnecessary glib.h includes 2016-06-07 18:19:24 +03:00
nvme-test.c tests: Remove unnecessary glib.h includes 2016-06-07 18:19:24 +03:00
pc-cpu-test.c tests: pc-cpu-test leaks fixes 2016-09-08 18:05:22 +04:00
pcnet-test.c tests: Remove unnecessary glib.h includes 2016-06-07 18:19:24 +03:00
pkix_asn1_tab.c qtest: fix make check complaint in crypto module 2016-10-19 10:09:24 +01:00
pnv-xscom-test.c tests: add XSCOM tests for the PowerNV machine 2016-11-15 11:38:18 +11:00
postcopy-test.c tests/postcopy: Use KVM on ppc64 only if it is KVM-HV 2016-11-23 12:00:48 +11:00
prom-env-test.c tests: Add pseries machine to the prom-env-test, too 2016-10-28 11:17:31 +11:00
ptimer-test-stubs.c tests: ptimer: Change the copyright comment 2016-10-24 16:26:53 +01:00
ptimer-test.c tests: ptimer: Replace 10000 with 1 2016-10-24 16:26:53 +01:00
ptimer-test.h tests: ptimer: Change the copyright comment 2016-10-24 16:26:53 +01:00
pvpanic-test.c tests: Remove unnecessary glib.h includes 2016-06-07 18:19:24 +03:00
pxe-test.c tests/boot-sector: Use mkstemp() to create a unique file name 2016-10-14 10:06:47 +11:00
q35-test.c libqos: add PCI management in qtest_vboot()/qtest_shutdown() 2016-10-06 16:15:53 +11:00
qemu-iotests-quick.sh qemu-iotests: Speed up make check-block 2015-01-13 11:47:55 +00:00
qht-bench.c qht-bench: relax test_start/stop atomic accesses 2016-10-24 15:27:19 +02:00
qom-test.c tests: fix qom-test leaks 2016-09-08 18:05:21 +04:00
rcutorture.c tests: Remove unnecessary glib.h includes 2016-06-07 18:19:24 +03:00
rtas-test.c tests: don't check if qtest_spapr_boot() returns NULL 2016-10-28 09:36:58 +11:00
rtc-test.c tests: Remove unnecessary glib.h includes 2016-06-07 18:19:24 +03:00
rtl8139-test.c libqos: Change PCI accessors to take opaque BAR handle 2016-10-28 09:38:27 +11:00
spapr-phb-test.c spapr: Improved placement of PCI host bridges in guest memory map 2016-10-16 12:04:15 +11:00
tco-test.c libqos: Change PCI accessors to take opaque BAR handle 2016-10-28 09:38:27 +11:00
test-aio.c aio: add AioPollFn and io_poll() interface 2017-01-03 16:38:48 +00:00
test-arm-mptimer.c tests: Add tests for the ARM MPTimer 2016-10-24 16:26:54 +01:00
test-base64.c tests: Remove unnecessary glib.h includes 2016-06-07 18:19:24 +03:00
test-bitcnt.c tests: New test-bitcnt 2017-01-10 08:49:59 -08:00
test-bitops.c bitops.h: Implement half-shuffle and half-unshuffle ops 2016-06-17 15:23:51 +01:00
test-blockjob-txn.c blockjob: add block_job_start 2016-11-14 22:47:34 -05:00
test-blockjob.c blockjobs: split interface into public/private, Part 1 2016-11-01 08:04:56 -04:00
test-bufferiszero.c cutils: Add test for buffer_is_zero 2016-09-13 19:13:32 +02:00
test-char.c char: remove explicit_fe_open, use a set_handlers argument 2016-10-24 15:46:10 +02:00
test-clone-visitor.c qapi: Add new clone visitor 2016-07-06 10:52:04 +02:00
test-coroutine.c test-coroutine: test qemu_coroutine_entered() 2016-09-28 17:11:23 +01:00
test-crypto-afsplit.c include/qemu/osdep.h: Don't include qapi/error.h 2016-03-22 22:20:15 +01:00
test-crypto-block.c tests: No longer dependent on CONFIG_UUID 2016-09-23 11:42:52 +08:00
test-crypto-cipher.c crypto: add 3des-ede support when using libgcrypt/nettle 2016-12-21 14:26:26 +00:00
test-crypto-hash.c crypto: fix initialization of crypto in tests 2016-10-19 10:23:55 +01:00
test-crypto-hmac.c crypto: add HMAC algorithms testcases 2016-12-22 09:24:59 +00:00
test-crypto-ivgen.c include/qemu/osdep.h: Don't include qapi/error.h 2016-03-22 22:20:15 +01:00
test-crypto-pbkdf.c crypto: support more hash algorithms for pbkdf 2016-09-19 16:30:45 +01:00
test-crypto-secret.c crypto: remove temp files on completion of secrets test 2016-06-13 12:41:17 +01:00
test-crypto-tlscredsx509.c include/qemu/osdep.h: Don't include qapi/error.h 2016-03-22 22:20:15 +01:00
test-crypto-tlssession.c include/qemu/osdep.h: Don't include qapi/error.h 2016-03-22 22:20:15 +01:00
test-crypto-xts.c crypto: rename OUT to out in xts test to avoid clash on MinGW 2016-07-04 10:46:59 +01:00
test-cutils.c tests: fix test-cutils leaks 2016-09-08 17:57:32 +04:00
test-filter-mirror.c tests: Remove unnecessary glib.h includes 2016-06-07 18:19:24 +03:00
test-filter-redirector.c coccinelle: Remove unnecessary variables for function return value 2016-06-20 16:38:13 +02:00
test-hbitmap.c tests: Add test code for hbitmap serialization 2016-10-24 17:56:07 +02:00
test-int128.c int128: Use __int128 if available 2016-10-26 08:29:00 -07:00
test-io-channel-buffer.c tests: Clean up includes 2016-02-16 14:29:27 +00:00
test-io-channel-command.c include/qemu/osdep.h: Don't include qapi/error.h 2016-03-22 22:20:15 +01:00
test-io-channel-file.c include/qemu/osdep.h: Don't include qapi/error.h 2016-03-22 22:20:15 +01:00
test-io-channel-socket.c io: Add a QIOChannelSocket cleanup test 2016-10-27 09:13:10 +02:00
test-io-channel-tls.c crypto: fix initialization of crypto in tests 2016-10-19 10:23:55 +01:00
test-io-task.c tests: Rename qtests which have names ending "error" 2016-08-05 15:27:15 +01:00
test-iov.c tests: fix test-iov leaks 2016-09-08 17:57:32 +04:00
test-logging.c test-logging: don't hard-code paths in /tmp 2016-08-19 12:44:11 +01:00
test-mul64.c tests: Remove unnecessary glib.h includes 2016-06-07 18:19:24 +03:00
test-netfilter.c tests: Remove unnecessary glib.h includes 2016-06-07 18:19:24 +03:00
test-opts-visitor.c opts-visitor: Favor new visit_free() function 2016-07-06 10:52:04 +02:00
test-qdev-global-props.c tests: Remove unnecessary glib.h includes 2016-06-07 18:19:24 +03:00
test-qdist.c qdist: return "(empty)" instead of NULL when printing an empty dist 2016-08-03 18:44:56 +02:00
test-qemu-opts.c tests: Remove unnecessary glib.h includes 2016-06-07 18:19:24 +03:00
test-qga.c test-qga: Avoid qobject_from_jsonv("%"PRId64) 2016-12-05 17:09:34 +01:00
test-qht-par.c clean-includes: run it once more 2016-06-16 18:39:03 +02:00
test-qht.c test-qht: perform lookups under rcu_read_lock 2016-10-06 18:04:13 +02:00
test-qmp-commands.c qapi: rename QmpInputVisitor to QObjectInputVisitor 2016-10-25 16:25:54 +02:00
test-qmp-event.c tests: Remove unnecessary glib.h includes 2016-06-07 18:19:24 +03:00
test-qobject-input-strict.c qapi: rename QmpInputVisitor to QObjectInputVisitor 2016-10-25 16:25:54 +02:00
test-qobject-input-visitor.c tests: Avoid qobject_from_jsonf("%"PRId64) 2016-12-05 17:09:34 +01:00
test-qobject-output-visitor.c qapi: rename QmpOutputVisitor to QObjectOutputVisitor 2016-10-25 16:25:54 +02:00
test-rcu-list.c tests: Remove unnecessary glib.h includes 2016-06-07 18:19:24 +03:00
test-replication.c test-replication: fix leaks 2016-11-15 15:41:00 +00:00
test-string-input-visitor.c qapi: rename *qmp-*-visitor* to *qobject-*-visitor* 2016-10-25 16:25:48 +02:00
test-string-output-visitor.c qapi: rename *qmp-*-visitor* to *qobject-*-visitor* 2016-10-25 16:25:48 +02:00
test-thread-pool.c coroutine: move entry argument to qemu_coroutine_create 2016-07-13 13:26:02 +02:00
test-throttle.c throttle: Test burst limits lower than the normal limits 2016-08-05 09:59:06 +01:00
test-timed-average.c tests: Remove unnecessary glib.h includes 2016-06-07 18:19:24 +03:00
test-uuid.c test-uuid: fix leak 2016-11-11 20:53:23 +08:00
test-visitor-serialization.c qapi: rename QmpOutputVisitor to QObjectOutputVisitor 2016-10-25 16:25:54 +02:00
test-vmstate.c tests/test-vmstate.c: add array of pointer to struct 2016-11-14 14:50:56 +01:00
test-write-threshold.c tests: Remove unnecessary glib.h includes 2016-06-07 18:19:24 +03:00
test-x86-cpuid-compat.c target-i386: Print warning when mixing [+-]foo and foo=(on|off) 2016-10-31 16:20:59 -02:00
test-x86-cpuid.c tests: Remove unnecessary glib.h includes 2016-06-07 18:19:24 +03:00
test-xbzrle.c util: move declarations out of qemu-common.h 2016-03-22 22:20:17 +01:00
tmp105-test.c tests: Remove unnecessary glib.h includes 2016-06-07 18:19:24 +03:00
tpci200-test.c tests: Remove unnecessary glib.h includes 2016-06-07 18:19:24 +03:00
usb-hcd-ehci-test.c libqos: Change PCI accessors to take opaque BAR handle 2016-10-28 09:38:27 +11:00
usb-hcd-ohci-test.c tests: Remove unnecessary glib.h includes 2016-06-07 18:19:24 +03:00
usb-hcd-uhci-test.c tests: minor cleanups in usb-hcd-uhci-test 2016-10-14 10:06:47 +11:00
usb-hcd-xhci-test.c tests: Remove unnecessary glib.h includes 2016-06-07 18:19:24 +03:00
vhost-user-bridge.c tests/vhost-user-bridge: use contrib/libvhost-user 2016-12-16 01:14:38 +02:00
vhost-user-test.c trivial patches for 2016-10-28 2016-10-31 11:58:30 +00:00
virtio-9p-test.c tests: virtio-9p: ".." cannot be used to walk out of the shared directory 2017-01-03 17:28:44 +01:00
virtio-balloon-test.c tests: Remove unnecessary glib.h includes 2016-06-07 18:19:24 +03:00
virtio-blk-test.c libqos: Give qvirtio_config_read*() consistent semantics 2016-10-28 09:38:27 +11:00
virtio-console-test.c coccinelle: Remove unnecessary variables for function return value 2016-06-20 16:38:13 +02:00
virtio-net-test.c tests: enable virtio tests on SPAPR 2016-10-28 09:36:58 +11:00
virtio-rng-test.c tests: enable virtio tests on SPAPR 2016-10-28 09:36:58 +11:00
virtio-scsi-test.c libqos: Give qvirtio_config_read*() consistent semantics 2016-10-28 09:38:27 +11:00
virtio-serial-test.c tests: Remove unnecessary glib.h includes 2016-06-07 18:19:24 +03:00
vmxnet3-test.c tests: Remove unnecessary glib.h includes 2016-06-07 18:19:24 +03:00
wdt_ib700-test.c coccinelle: Remove unnecessary variables for function return value 2016-06-20 16:38:13 +02:00