Daniel P. Berrangé <berra...@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 <th...@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``.
