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>
---
 hmp.c             | 2 +-
 qapi/misc.json    | 6 +++---
 qemu-options.hx   | 9 +++++----
 qemu-tech.texi    | 8 ++++----
 qmp.c             | 2 +-
 tests/numa-test.c | 2 +-
 tests/qmp-test.c  | 6 +++---
 7 files changed, 18 insertions(+), 17 deletions(-)

diff --git a/hmp.c b/hmp.c
index fe4477a8fb..3e689dfc6b 100644
--- a/hmp.c
+++ b/hmp.c
@@ -1074,7 +1074,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);
 }
 
diff --git a/qapi/misc.json b/qapi/misc.json
index 29da7856e3..2e9902371a 100644
--- a/qapi/misc.json
+++ b/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:
diff --git a/qemu-options.hx b/qemu-options.hx
index 16208f63f2..1d04613a17 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -3291,16 +3291,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
-the preconfig state and move to the next state (ie. run guest if -S
-isn't used or pause the second time if -S is used).
+machine initialization.  Use QMP command 'x-exit-preconfig' to exit
+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).  This option is
+experimental.
 ETEXI
 
 DEF("S", 0, QEMU_OPTION_S, \
diff --git a/qemu-tech.texi b/qemu-tech.texi
index f843341ffa..7c3d1f05e1 100644
--- a/qemu-tech.texi
+++ b/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
-when the --preconfig command line option should be used. It allows pausing QEMU
-before the initial VM creation, in a new preconfig state, where additional
+initial VM creation (like: -smp/-m/-numa ...) or cold plug devices. The
+experimental --preconfig command line option  allows pausing QEMU
+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
diff --git a/qmp.c b/qmp.c
index 73e46d795f..411e3210bb 100644
--- a/qmp.c
+++ b/qmp.c
@@ -161,7 +161,7 @@ SpiceInfo *qmp_query_spice(Error **errp)
 };
 #endif
 
-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",
diff --git a/tests/numa-test.c b/tests/numa-test.c
index b7a6ef8815..893f826acb 100644
--- a/tests/numa-test.c
+++ b/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 */
diff --git a/tests/qmp-test.c b/tests/qmp-test.c
index a49cbc6fde..ca8c599526 100644
--- a/tests/qmp-test.c
+++ b/tests/qmp-test.c
@@ -412,7 +412,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 */
@@ -422,8 +422,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 */
-    g_assert(qmp_rsp_is_err(qtest_qmp(qs, "{ 'execute': 'exit-preconfig' }")));
+    /* check that x-exit-preconfig returns error after exiting 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' }")));
-- 
2.17.1

On 07/05/2018 04:14 AM, Markus Armbruster wrote:
> 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.

Should the CLI be spelled --x-preconfig?

> 
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> ---

Other than the potential for a spelling change,
Reviewed-by: Eric Blake <eblake@redhat.com>

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org

Eric Blake <eblake@redhat.com> writes:

> On 07/05/2018 04:14 AM, Markus Armbruster wrote:
>> 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.
>
> Should the CLI be spelled --x-preconfig?

Would be the first use of x- with option names.

Since you have to pair --preconfig with x-exit-preconfig, I figure
slapping x- onto the latter suffices.  But I'm not opposed to slapping
it onto the former as well.

>> Signed-off-by: Markus Armbruster <armbru@redhat.com>
>> ---
>
> Other than the potential for a spelling change,
> Reviewed-by: Eric Blake <eblake@redhat.com>

Thanks!

On 07/05/2018 04:14 AM, Markus Armbruster wrote:
> 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.

One additional point - the fact that 'x-exit-preconfig' vs. 
'exit-preconfig' is introspectable means that even if we decide to 
cement the ABI at a time when libvirt is taught to use it, libvirt will 
know that 3.0's version is not the final form of the feature (ideally, 
of course, we'll be able to fix qemu to avoid the need for the 
--preconfig hack in the first place...)

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org