Re: How to mark internal properties

[Markus Armbruster <armbru@redhat.com>]

Daniel P. Berrangé <berrange@redhat.com> writes:

> On Mon, May 12, 2025 at 09:46:30AM +0100, Peter Maydell wrote:
>> On Fri, 9 May 2025 at 11:04, Thomas Huth <thuth@redhat.com> wrote:
>> > Thanks for your clarifications, Zhao! But I think this shows again the
>> > problem that we have hit a couple of times in the past already: Properties
>> > are currently used for both, config knobs for the users and internal
>> > switches for configuration of the machine. We lack a proper way to say "this
>> > property is usable for the user" and "this property is meant for internal
>> > configuration only".
>> >
>> > I wonder whether we could maybe come up with a naming scheme to better
>> > distinguish the two sets, e.g. by using a prefix similar to the "x-" prefix
>> > for experimental properties? We could e.g. say that all properties starting
>> > with a "q-" are meant for QEMU-internal configuration only or something
>> > similar (and maybe even hide those from the default help output when running
>> > "-device xyz,help" ?)? Anybody any opinions or better ideas on this?
>> 
>> I think a q-prefix is potentially a bit clunky unless we also have
>> infrastructure to say eg DEFINE_INTERNAL_PROP_BOOL("foo", ...)
>> and have it auto-add the prefix, and to have the C APIs for
>> setting properties search for both "foo" and "q-foo" so you
>> don't have to write qdev_prop_set_bit(dev, "q-foo", ...).

If we make intent explicit with DEFINE_INTERNAL_PROP_FOO(), is repeating
intent in the name useful?

> I think it is also not obvious enough that a 'q-' prefix means private.

Concur.

> Perhaps borrow from the C world and declare that a leading underscore
> indicates a private property. People are more likely to understand and
> remember that, than 'q-'.

This is fine for device properties now.  It's not fine for properties of
user-creatable objects, because these are defined in QAPI, and QAPI
prohibits names starting with a single underscore.  I append relevant
parts of docs/devel/qapi-code-gen.rst for your convenience.

Why does QAPI prohibit leading underscores?  Chiefly because such names
are reserved identifiers in C.  Instead of complicating the mapping from
QAPI name to C identifier, we restrict QAPI names and call it a day.

The mapping between device property name and C identifiers is entirely
manual.  When a property is backed by a member of the device state
struct, naming the member exactly like the property makes sense.  Having
to mentally strip / insert a leading underscore would hardly be
terrible, just a bit of friction.  I'd prefer not to.




Naming rules and reserved names
-------------------------------

All names must begin with a letter, and contain only ASCII letters,
digits, hyphen, and underscore.  There are two exceptions: enum values
may start with a digit, and names that are downstream extensions (see
section `Downstream extensions`_) start with underscore.

Names beginning with ``q_`` are reserved for the generator, which uses
them for munging QMP names that resemble C keywords or other
problematic strings.  For example, a member named ``default`` in qapi
becomes ``q_default`` in the generated C code.

[...]

Downstream extensions
---------------------

QAPI schema names that are externally visible, say in the Client JSON
Protocol, need to be managed with care.  Names starting with a
downstream prefix of the form __RFQDN_ are reserved for the downstream
who controls the valid, reverse fully qualified domain name RFQDN.
RFQDN may only contain ASCII letters, digits, hyphen and period.

Example: Red Hat, Inc. controls redhat.com, and may therefore add a
downstream command ``__com.redhat_drive-mirror``.