cli qmp: Mark --preconfig, exit-preconfig experimental

Committing to the current --preconfig / exit-preconfig interface
before it has seen any use is premature.  Mark both as experimental,
the former in documentation, the latter by renaming it to
x-exit-preconfig.

See the previous commit for more detailed rationale.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20180705091402.26244-3-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Acked-by: Eduardo Habkost <ehabkost@redhat.com>
Acked-by: Igor Mammedov <imammedo@redhat.com>
[Straightforward conflict with commit 514337c142 resolved]

hmp.c

@@ -1076,7 +1076,7 @@ void hmp_exit_preconfig(Monitor *mon, const QDict *qdict)
 {
     Error *err = NULL;
 
-    qmp_exit_preconfig(&err);
+    qmp_x_exit_preconfig(&err);
     hmp_handle_error(mon, &err);
 }
 

qapi/misc.json

@@ -1205,7 +1205,7 @@
 { 'command': 'cont' }
 
 ##
-# @exit-preconfig:
+# @x-exit-preconfig:
 #
 # Exit from "preconfig" state
 #
@@ -1221,11 +1221,11 @@
 #
 # Example:
 #
-# -> { "execute": "exit-preconfig" }
+# -> { "execute": "x-exit-preconfig" }
 # <- { "return": {} }
 #
 ##
-{ 'command': 'exit-preconfig', 'allow-preconfig': true }
+{ 'command': 'x-exit-preconfig', 'allow-preconfig': true }
 
 ##
 # @system_wakeup:

qemu-options.hx

@@ -3303,16 +3303,17 @@ Run the emulation in single step mode.
 ETEXI
 
 DEF("preconfig", 0, QEMU_OPTION_preconfig, \
-    "--preconfig     pause QEMU before machine is initialized\n",
+    "--preconfig     pause QEMU before machine is initialized (experimental)\n",
     QEMU_ARCH_ALL)
 STEXI
 @item --preconfig
 @findex --preconfig
 Pause QEMU for interactive configuration before the machine is created,
 which allows querying and configuring properties that will affect
-machine initialization. Use the QMP command 'exit-preconfig' to exit
+machine initialization.  Use QMP command 'x-exit-preconfig' to exit
-the preconfig state and move to the next state (ie. run guest if -S
+the preconfig state and move to the next state (i.e. run guest if -S
-isn't used or pause the second time if -S is used).
+isn't used or pause the second time if -S is used).  This option is
+experimental.
 ETEXI
 
 DEF("S", 0, QEMU_OPTION_S, \

qemu-tech.texi

@@ -336,9 +336,9 @@ additionally configure the machine (by hotplugging devices) in runtime before
 allowing VM code to run.
 
 However, at the -S pause point, it's impossible to configure options that affect
-initial VM creation (like: -smp/-m/-numa ...) or cold plug devices. That's
+initial VM creation (like: -smp/-m/-numa ...) or cold plug devices. The
-when the --preconfig command line option should be used. It allows pausing QEMU
+experimental --preconfig command line option  allows pausing QEMU
-before the initial VM creation, in a new preconfig state, where additional
+before the initial VM creation, in a ``preconfig'' state, where additional
 queries and configuration can be performed via QMP before moving on to
 the resulting configuration startup. In the preconfig state, QEMU only allows
 a limited set of commands over the QMP monitor, where the commands do not
@@ -348,7 +348,7 @@ depend on an initialized machine, including but not limited to:
 @item query-qmp-schema
 @item query-commands
 @item query-status
-@item exit-preconfig
+@item x-exit-preconfig
 @end table
 
 @node Bibliography

qmp.c

@@ -129,7 +129,7 @@ void qmp_cpu_add(int64_t id, Error **errp)
     }
 }
 
-void qmp_exit_preconfig(Error **errp)
+void qmp_x_exit_preconfig(Error **errp)
 {
     if (!runstate_check(RUN_STATE_PRECONFIG)) {
         error_setg(errp, "The command is permitted only in '%s' state",

tests/numa-test.c

@@ -285,7 +285,7 @@ static void pc_dynamic_cpu_cfg(const void *data)
         " 'arguments': { 'type': 'cpu', 'node-id': 1, 'socket-id': 0 } }")));
 
     /* let machine initialization to complete and run */
-    g_assert(!qmp_rsp_is_err(qtest_qmp(qs, "{ 'execute': 'exit-preconfig' }")));
+    g_assert(!qmp_rsp_is_err(qtest_qmp(qs, "{ 'execute': 'x-exit-preconfig' }")));
     qtest_qmp_eventwait(qs, "RESUME");
 
     /* check that CPUs are mapped as expected */

tests/qmp-test.c

@@ -453,7 +453,7 @@ static void test_qmp_preconfig(void)
     qobject_unref(rsp);
 
     /* exit preconfig state */
-    g_assert(!qmp_rsp_is_err(qtest_qmp(qs, "{ 'execute': 'exit-preconfig' }")));
+    g_assert(!qmp_rsp_is_err(qtest_qmp(qs, "{ 'execute': 'x-exit-preconfig' }")));
     qtest_qmp_eventwait(qs, "RESUME");
 
     /* check that query-status returns running state */
@@ -463,8 +463,8 @@ static void test_qmp_preconfig(void)
     g_assert_cmpstr(qdict_get_try_str(ret, "status"), ==, "running");
     qobject_unref(rsp);
 
-    /* check that exit-preconfig returns error after exiting preconfig */
+    /* check that x-exit-preconfig returns error after exiting preconfig */
-    g_assert(qmp_rsp_is_err(qtest_qmp(qs, "{ 'execute': 'exit-preconfig' }")));
+    g_assert(qmp_rsp_is_err(qtest_qmp(qs, "{ 'execute': 'x-exit-preconfig' }")));
 
     /* enabled commands, no error expected  */
     g_assert(!qmp_rsp_is_err(qtest_qmp(qs, "{ 'execute': 'query-cpus' }")));