Re: [PATCH v3 4/4] migration/qapi: Drop @MigrationParameter enum

[Peter Xu <peterx@redhat.com>]

On Wed, Sep 06, 2023 at 11:46:16AM +0100, Daniel P. Berrangé wrote:
> On Wed, Sep 06, 2023 at 12:14:54PM +0200, Philippe Mathieu-Daudé wrote:
> > On 6/9/23 11:00, Daniel P. Berrangé wrote:
> > > On Wed, Sep 06, 2023 at 06:42:16AM +0200, Philippe Mathieu-Daudé wrote:
> > > > On 5/9/23 18:23, Peter Xu wrote:
> > > > > Drop the enum in qapi because it is never used in QMP APIs.  Instead making
> > > > > it an internal definition for QEMU so that we can decouple it from QAPI,
> > > > > and also we can deduplicate the QAPI documentations.
> > > > > 
> > > > > Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
> > > > > Signed-off-by: Peter Xu <peterx@redhat.com>
> > > > > ---
> > > > >    qapi/migration.json            | 179 ---------------------------------
> > > > >    migration/options.h            |  47 +++++++++
> > > > >    migration/migration-hmp-cmds.c |   3 +-
> > > > >    migration/options.c            |  51 ++++++++++
> > > > >    4 files changed, 100 insertions(+), 180 deletions(-)
> > > > 
> > > > 
> > > > > diff --git a/migration/options.h b/migration/options.h
> > > > > index 124a5d450f..4591545c62 100644
> > > > > --- a/migration/options.h
> > > > > +++ b/migration/options.h
> > > > > @@ -66,6 +66,53 @@ bool migrate_cap_set(int cap, bool value, Error **errp);
> > > > >    /* parameters */
> > > > > +typedef enum {
> > > > > +    MIGRATION_PARAMETER_ANNOUNCE_INITIAL,
> > > > > +    MIGRATION_PARAMETER_ANNOUNCE_MAX,
> > > > > +    MIGRATION_PARAMETER_ANNOUNCE_ROUNDS,
> > > > > +    MIGRATION_PARAMETER_ANNOUNCE_STEP,
> > > > > +    MIGRATION_PARAMETER_COMPRESS_LEVEL,
> > > > > +    MIGRATION_PARAMETER_COMPRESS_THREADS,
> > > > > +    MIGRATION_PARAMETER_DECOMPRESS_THREADS,
> > > > > +    MIGRATION_PARAMETER_COMPRESS_WAIT_THREAD,
> > > > > +    MIGRATION_PARAMETER_THROTTLE_TRIGGER_THRESHOLD,
> > > > > +    MIGRATION_PARAMETER_CPU_THROTTLE_INITIAL,
> > > > > +    MIGRATION_PARAMETER_CPU_THROTTLE_INCREMENT,
> > > > > +    MIGRATION_PARAMETER_CPU_THROTTLE_TAILSLOW,
> > > > > +    MIGRATION_PARAMETER_TLS_CREDS,
> > > > > +    MIGRATION_PARAMETER_TLS_HOSTNAME,
> > > > > +    MIGRATION_PARAMETER_TLS_AUTHZ,
> > > > > +    MIGRATION_PARAMETER_MAX_BANDWIDTH,
> > > > > +    MIGRATION_PARAMETER_DOWNTIME_LIMIT,
> > > > > +    MIGRATION_PARAMETER_X_CHECKPOINT_DELAY,
> > > > > +    MIGRATION_PARAMETER_BLOCK_INCREMENTAL,
> > > > > +    MIGRATION_PARAMETER_MULTIFD_CHANNELS,
> > > > > +    MIGRATION_PARAMETER_XBZRLE_CACHE_SIZE,
> > > > > +    MIGRATION_PARAMETER_MAX_POSTCOPY_BANDWIDTH,
> > > > > +    MIGRATION_PARAMETER_MAX_CPU_THROTTLE,
> > > > > +    MIGRATION_PARAMETER_MULTIFD_COMPRESSION,
> > > > > +    MIGRATION_PARAMETER_MULTIFD_ZLIB_LEVEL,
> > > > > +    MIGRATION_PARAMETER_MULTIFD_ZSTD_LEVEL,
> > > > > +    MIGRATION_PARAMETER_BLOCK_BITMAP_MAPPING,
> > > > > +    MIGRATION_PARAMETER_X_VCPU_DIRTY_LIMIT_PERIOD,
> > > > > +    MIGRATION_PARAMETER_VCPU_DIRTY_LIMIT,
> > > > > +    MIGRATION_PARAMETER__MAX,
> > > > 
> > > > MIGRATION_PARAMETER__MAX is not part of the enum, so:
> > > > 
> > > >     #define MIGRATION_PARAMETER__MAX \
> > > >         (MIGRATION_PARAMETER_VCPU_DIRTY_LIMIT + 1)
> > > 
> > > IMHO the way it currently is written is better, because the
> > > __MAX value is guaranteed to always have the right max value
> > > without needing to be manually changed when new params are
> > > added. Note this matches the code style used by the QAPI
> > > enum generator too.
> > 
> > This concern comes from a previous discussion with Richard (which I
> > can't find now in the archives) where he explained to me __MAX is not
> > part of the enum set, thus reduces the coverage of compiler sanitizers
> > / optimizers, and could introduce subtle bugs.
> > 
> > This motivated this series:
> > https://lore.kernel.org/qemu-devel/20230315112811.22355-4-philmd@linaro.org/
> > which should have changed that generated QAPI enum.
> > 
> > (I didn't respin that series because I couldn't find an easy way to
> >  handle conditionals, see
> >  https://lore.kernel.org/qemu-devel/87sfdyaq0m.fsf@pond.sub.org/)
> 
> Oh, I completely forgot about that series.
> 
> So the original problem is that with '-Wswitch' present, if  the
> switched variable is an enum type, the compiler complains if you
> don't list all possible enum values, or have a default: clause.
> 
> Thus the existance of __MAX forces use to add case ...__MAX, or
> have a default, and you wanted to eliminate that requirement.
> 
> Or the surface that sounds reasonable, but I actually think that
> is the conceptually wrong approach from a robustness POV.
> 
> C (and some other languages) are terrible wrt enum declared
> constants vs actual stored values.
> 
> You can have a variable declared KeyValueKind and it can store
> absolutely any integer value at all, whether intentionally,
> or by a code mistake or by data corruption.
> 
> In your example you modified:
> 
>         switch (key->key->type) {
>         case KEY_VALUE_KIND_NUMBER:
>             qcode = qemu_input_key_number_to_qcode(key->key->u.number.data);
>             name = QKeyCode_str(qcode);
>             trace_input_event_key_number(idx, key->key->u.number.data,
>                                          name, key->down);
>             break;
>         case KEY_VALUE_KIND_QCODE:
>             name = QKeyCode_str(key->key->u.qcode.data);
>             trace_input_event_key_qcode(idx, name, key->down);
>             break;
>         case KEY_VALUE_KIND__MAX:
>             /* keep gcc happy */
>             break;
>         }
> 
> to remove KEY_VALUE_KIND__MAX.
> 
> What we should actually do IMHO is to either change it to
> 
>    default:
>        g_assert_not_reached();
> 
> Or get extra paranoid and  -Wswitch-enum too and list both
> together
> 
>    case KEY_VALUE_KIND__MAX:
>    default:
>        g_assert_not_reached();
> 
> This forces us to validate every enum case, and also protect
> against out of range values.
> 
> This is a little more verbose to code, but I can't say it
> has been a maint problem in libvirt where we've followed
> this approach with -Wswitch-enum and _MAX constants.
> 
> > Back to this patch, I don't object to having MIGRATION_PARAMETER__MAX
> > in the enum, but I'd rather have the suggestion below considered.
> 
> I just prefer to see consistency in approach across the codebase, and
> currently we use __MAX approach.

Personally I prefer the same.

I'll squash below change into the patch (with Phil's R-b):

===============
diff --git a/migration/options.h b/migration/options.h
index 4591545c62..2e4fa17351 100644
--- a/migration/options.h
+++ b/migration/options.h
@@ -99,8 +99,7 @@ typedef enum {
     MIGRATION_PARAMETER__MAX,
 } MigrationParameter;
 
-extern const char *MigrationParameter_string[MIGRATION_PARAMETER__MAX];
-#define  MigrationParameter_str(p)  MigrationParameter_string[p]
+const char *MigrationParameter_str(MigrationParameter p);
 
 /**
  * @MigrationParameter_from_str(): Parse string into a MigrationParameter
diff --git a/migration/options.c b/migration/options.c
index c9b90d932d..e87c9667d1 100644
--- a/migration/options.c
+++ b/migration/options.c
@@ -84,7 +84,7 @@
 #define DEFAULT_MIGRATE_VCPU_DIRTY_LIMIT_PERIOD     1000    /* milliseconds */
 #define DEFAULT_MIGRATE_VCPU_DIRTY_LIMIT            1       /* MB/s */
 
-const char *MigrationParameter_string[MIGRATION_PARAMETER__MAX] = {
+static const char *const MigrationParameter_string[MIGRATION_PARAMETER__MAX] = {
     [MIGRATION_PARAMETER_ANNOUNCE_INITIAL] = "announce-initial",
     [MIGRATION_PARAMETER_ANNOUNCE_MAX] = "announce-max",
     [MIGRATION_PARAMETER_ANNOUNCE_ROUNDS] = "announce-rounds",
@@ -116,6 +116,11 @@ const char *MigrationParameter_string[MIGRATION_PARAMETER__MAX] = {
     [MIGRATION_PARAMETER_VCPU_DIRTY_LIMIT] = "vcpu-dirty-limit",
 };
 
+const char *MigrationParameter_str(MigrationParameter p)
+{
+    return MigrationParameter_string[p];
+}
+
 int MigrationParameter_from_str(const char *param, Error **errp)
 {
     int i;
===============

Thanks,

-- 
Peter Xu