On Sat, Apr 02, 2022 at 12:40:57AM +0200, Victor Toso wrote:
> This patch handles QAPI enum types and generates its equivalent in Go.
>
> The highlights of this implementation are:
>
> 1. For each QAPI enum, we will define an int32 type in Go to be the
> assigned type of this specific enum
I think there's a potential case to be made for considering
representation of enums as strings in Golang, as it more
gracefully degrades.
Consider the 'SHUTDOWN' event in QEMU, which has a 'reason' field.
This implementation has
type ShutdownCause int32
const (
ShutdownCauseNone ShutdownCause = iota
ShutdownCauseHostError // An error prevents
further use of guest
ShutdownCauseHostQmpQuit // Reaction to the QMP
command 'quit'
ShutdownCauseHostQmpSystemReset // Reaction to the QMP
command 'system_reset'
ShutdownCauseHostSignal // Reaction to a signal,
such as SIGINT
ShutdownCauseHostUi // Reaction to a UI
event, like window close
ShutdownCauseGuestShutdown // Guest shutdown/suspend
request, via ACPI or other hardware-specific means
ShutdownCauseGuestReset // Guest reset request,
and command line turns that into a shutdown
ShutdownCauseGuestPanic // Guest panicked, and
command line turns that into a shutdown
ShutdownCauseSubsystemReset // Partial guest reset
that does not trigger QMP events and ignores --no-reboot. This is useful for
sanitizing hypercalls on s390 that are used during kexec/kdump/boot
)
and
type ShutdownEvent struct {
Guest bool `json:"guest"` // If true, the shutdown was
triggered by a guest request (such as a guest-initiated ACPI shutdown request
or other hardware-specific action) rather than a host request (such as sending
qemu a SIGINT). (since 2.10)
Reason ShutdownCause `json:"reason"` // The @ShutdownCause which
resulted in the SHUTDOWN. (since 4.0)
}
Consider that the application is compiled against the QAPI generated
API from QEMU 7.0. The application is believed to run happily against
7.1, because app doesn't need any of the functionality added in 7.1
QAPI. But consider that QEMU 7.1 had introduced a new shutdown reason
value.
The application may want to know that the guest has shutdown, but does
NOT care about the reason for the shutdown.
Since the ShutdownReason is implemented as an int though, the unmarshalling
for the reason field is going to fail.
If the enums were just represented as strings, then we can gracefully
accept any new enum value that arrives in future. The application can
thus also still log the shutdown reason string, even though it was not
a value explicitly known to the generated API.
>
> 2. While in the Go codebase we can use the generated enum values, the
> specification requires that, on the wire, the enumeration type's
> value to be represented by its string name.
>
> For this reason, each Go type that represent's a QAPI enum will be
> implementing the Marshaler[0] and Unmarshaler[1] interfaces to
> seamless handle QMP's string to Go int32 value and vice-versa.
>
> 3. Naming: CamelCase will be used in any identifier that we want to
> export [2], which is everything in this patch.
With regards,
Daniel
--
|: https://berrange.com -o- https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org -o- https://fstop138.berrange.com :|
|: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
