The libnbd project has a documented registration system where
third-party implementations can include a link to their stable
documentation of meta-contexts.  Qemu was the first project to utilize
this process[1], by pointing to documentation on its own
meta-contexts[2].  And in libnbd, we even foreshadowed the need to
document future meta-contexts by creating metadata_namespaces as a
list even when it started out with only one element.  It's time to
extend that list to include the qemu contexts.

[1] https://github.com/NetworkBlockDevice/nbd/commit/e96b311caf901
[2] https://gitlab.com/qemu-project/qemu/-/blob/master/docs/interop/nbd.txt



"qemu:dirty-bitmap:NAME" is a set of namespaces for any arbitrary
dirty bitmap name; we can't define a constant for every possible dirty
bitmap name, but it is possible to do NBD_OPT_LIST_META_CONTEXT on
"qemu:dirty-bitmap:" to see which dirty bitmaps are available.  When a
dirty bitmap is negotiated, only one bit is defined (an extent is
dirty or not).  The presence of '-' and ':' in the context name beyond
the namespace requires a new helper function.

"qemu:allocation-depth" returns an integer rather than a bitmap (0 for
unmapped, 1 for current image, 2 and beyond for number of files in the
backing chain before the data was supplied); as that is rather
open-ended, for now we are not defining any constants for interpreting
its values (but could always add some later).

And in the process of having two contexts under one namespace, where
not all of the contexts have any associated constants, it required two
passes instead of one over the list for output that is easier to read.

For libnbd.h, the generated diff is:

| --- include/libnbd.h.bak	2023-07-26 11:01:45.401328604 -0500
| +++ include/libnbd.h	2023-07-26 11:59:38.289021067 -0500
| @@ -1083,6 +1083,16 @@
|  #define LIBNBD_STATE_HOLE                     1
|  #define LIBNBD_STATE_ZERO                     2
|
| +/* "qemu" namespace */
| +#define LIBNBD_NAMESPACE_QEMU "qemu:"
| +
| +/* "qemu" namespace contexts */
| +#define LIBNBD_CONTEXT_QEMU_DIRTY_BITMAP "qemu:dirty-bitmap:"
| +#define LIBNBD_CONTEXT_QEMU_ALLOCATION_DEPTH "qemu:allocation-depth"
| +
| +/* "qemu:dirty-bitmap:" context related constants */
| +#define LIBNBD_STATE_DIRTY                    1
| +
|  #ifdef __cplusplus
|  }
|  #endif

Signed-off-by: Eric Blake <eblake@redhat.com>
Message-ID: <20230726173441.855563-2-eblake@redhat.com>
[eblake: improve commit message]
Acked-by: Laszlo Ersek <lersek@redhat.com>