[Qemu-devel] BB name vs. BDS name in the QAPI schema

[Markus Armbruster]

This has been discussed on IRC, but I want it on the list for further
discussion and later reference.

Terminology: BDS = BlockDriverState, BB = BlockBackend

Traditionally, only root BDSes could be named.  They're always uniquely
named; if the user doesn't supply a name via -drive parameter "id", the
system makes one up.  This name is stored in BDS member device_name[].
In the QAPI schema, it's called "device", both in arguments and in
results.

Having a name is not the only property that makes root BDSes special.
More on that below.

Kevin's "blockdev-add QMP command" series (commit 52c8d62..b681072, Sep
2013) adds a way to name interior nodes, not just roots.  It names the
blockdev-add parameter "id" rather to the "device".

Benoît's "Giving names to graph's BlockDriverState" series (commit
c8059b9..0901f67, Jan 2014) adds the node-name concept.  When define
BDSes, the user can give them a unique node-name, with blockdev-add
parameter "node-name".  -drive supports it, too.  This name is stored in
BDS member node_name[].  In the QAPI schema, it's usually called
"node-name".

Aside: a couple of QMP commands predating node names identify an
interior BDS by its BB name and a backing "filename".  Resolves to the
first BDSes below BB whose "filename" matches.  These should all be
updated to work with BDS names instead.

Node names are in the same name space as the device names.  Without
that, a name could be ambiguous unless you know whether it's a device
name or a node name.

We exploit that in the schema: anonymous union BlockdevRef has a string
member "reference", and both kinds of names are valid there.  Introduced
by Kevin's blockdev-add series, i.e. it predates node names.  Used to
connect sub-trees with blockdev-add.

In other words, the node names series extends BlockdevRef to accept node
names in addition to device names.  Good, because *want* to be able to
use them to connect sub-trees with blockdev-add.

Wherever else the ability to use both device and node names is wanted,
however, we use a pair of parameters, usually "device" and "node-name".
You can use either one or the other, not both.

I'm currently working on putting a BB on top of each root BDS[*].  First
step towards moving all the "root specialness" from BDS to BB, leaving
the root BDS non-special.  In this world, device_name[] moves from BDS
to BB.

Thus, the two kinds of names become BB names (a.k.a. device names) and
BDS names (a.k.a. node-names).

Since BB names and BDS names share a namespace, a name unambiguously
resolves either to a BB, a BDS, or nothing.

In places where we want to name a BB, the schema has a parameter,
usually named "device", and its valid values are the BB names.

In places where we want to name a BDS, the schema has either

* Two parameters, usually named "device" and "node-name", valid values
  for the former are the BB names, and for the latter the BDS names.

* A single parameter, and both BB names and BDS names are valid values.

Either way, naming a BB really names its BDS.  No change from before the
introduction of BBs, because then the name still belonged to that BDS.

Having two different ways to do the same thing bothers me.  What about
you?

If it bothers us: can we do something about it?

I actually like having separate parameters for separate kinds of names.  

However, BlockdevRef appears to tie our hand: it's an anonymous union,
which means only the value is on the wire, and the receiving end uses
its type to determine which union member it is.  Both kinds of names are
strings, so we can't have separate union members for them.

Opinions?


[*] [PATCH v2 00/23] Split BlockBackend off BDS with an axe