Re: [PATCH v2] qdev: Clarify instantiation and realization

[Markus Armbruster <armbru@redhat.com>]

Peter Maydell <peter.maydell@linaro.org> writes:

> On Mon, 13 Jul 2026 at 14:20, Markus Armbruster <armbru@redhat.com> wrote:
>>
>> Peter Maydell <peter.maydell@linaro.org> writes:
>> > OK. We could make the text clearer then, I think. Maybe
>> >
>> > "#TypeInfo.instance_init may not fail. #DeviceClass.realize can
>> > fail, returning error information to the caller. A device realize
>> > method should handle being called again after it has failed once."
>> >
>> > ?
>>
>> In general, a function should either do its job, or fail cleanly,
>> i.e. without side effects.
>>
>> For .realize() "without side effects" includes:
>>
>> * The failed call is invisible to the guest.
>>
>> * The device behaves as if the failed call never happened.  This means
>>   you can try .realize() again.
>>
>> Does the comment need to spell this out?
>
> If we want that, I think we should spell it out. I have generally
> assumed when writing realize functions that the semantics are
> "if this fails, the only thing the caller can usefully do with
> the object is destroy it". Realize code very very rarely attempts
> to cleanly unwind if it finds an error partway through. I would
> expect the only cases where it works at all are the ones where
> the only errors are "sanity check of property values etc" that
> happens up front.
>
> I would prefer it if we did not require this, because I think
> it imposes extra burden on implementations in order to provide
> something that is not of any benefit to anybody.

No objection, as long as the function contract is clear.

> Analogy: for unix sockets, you need to first open() and then
> connect(). The connect() manpage and the POSIX spec say that if
> connect() fails the only thing you can validly do with the socket
> is call close(): you're not allowed to keep it around and try
> connect() or some other operation on it.
>
> (We also undoubtedly have a lot of bugs where an error in realize
> leaves bits of the device visible to the emulation, or doesn't
> free things that were allocated, etc. But that's a separate and
> uncontroversial kind of bug. We don't notice these because for
> almost all devices the response to "realize failed" is that we're
> going to exit QEMU, because the device is part of the machine.)

Yes.