[Proposal] VTY attributes in libraries

[Vadim Yanitskiy]

Hi all again,

this is a follow-up post continuing discussion on the VTY attributes.
Yesterday Philipp reached me out regarding adding 'when it applies'
attributes to VTY commands registered by our shared libraries, i.e.
libosmo-*.  The problem is that the current API does not allow to
register description and flag letters for such commands.

My initial idea was to introduce a simple function that would merge a
given set of library specific attributes into the application specific
attributes provided by the API user (see struct vty_app_info).  However,
this is not a solution, because there can be multiple libraries an
application dynamically links to, and there can be collisions not only
between attributes defined by a library and the application itself, but
what's even more problematic, between different libraries too.

        +----------+
    +---| LIB CORE |-----+
    |   +----------+     |
    |       |            |
    |   +---x---+    +---x---+
    |   | LIB A |    | LIB B |
    |   +-------+    +-------+
    |       |            |
    |   +---x------------x---+
    +---x    APPLICATION     |
        +--------------------+

This illustrates a typical situation when not only the 'APPLICATION'
itself defines its own VTY commands, and thus its own VTY attributes,
but also the libraries it is dynamically linked to optionally register
VTY commands and the related attributes.

Given that a single VTY command may store up to 32 unique attributes
(because it's a bit-mask based on unsigned int), we somehow need to
ensure that there is no clashes between the attributes and their
associated flag letters.

I also thought about reserving 16 LSBs of the bit-mask for attributes
defined by libraries, so this way all libosmo-* would need to somehow
share these reserved 16 bits, but...  Given that a VTY command can
either be an application's command *or* a library's command, splitting
the bit-mask does not make that much sense.

After a bit of brainstorming, I came up with a proposal:

a) applications are allowed to register up to 32 unique attributes with
optional flags: some symbols (to be discussed), numbers, or lowercase
letters;

b) libraries get their own *global* bit-space for attributes with
optional flags: some symbols (to be discussed) or uppercase letters;

c) all libraries *share* 32 unique attributes (and thus flags), because
an application may be using VTY commands of several libraries at the
same time;
c1) in other words, if let's say libosmo-abis defines attribute (1 <<
0), then none of the other libraries is allowed to redefine it;

d) all attributes belonging to libraries, together with their
description and optional flag letters, to be defined in a centralized
place - libosmocore (more precisely, libosmovty);
d1) this way we ensure that there are no clashes: neither between the
attribute values, nor between their flag letters.

A downside of this approach is that libosmovty would need to distinguish
VTY commands belonging to an application from commands registered by the
libraries it depends on.  This way it would be possible to pick the
correct attribute description (from struct vty_app_info or from
libosmocore) when generating the VTY documentation.  I propose:

e) to introduce one more global attribute CMD_ATTR_LIBCMD, and 'equip'
all VTY commands registered by libraries with it;
e1) in order to avoid mangling all existing DEFUNs, we can introduce
special install_element_lib() / install_element_ve_lib() wrappers and
use them.

I hope I have not forgotten anything.
Looking forward to know your opinion.

Best regards,
Vadim.

-- 
- Vadim Yanitskiy <vyanitskiy at sysmocom.de>    http://www.sysmocom.de/
=======================================================================
* sysmocom - systems for mobile communications GmbH
* Alt-Moabit 93
* 10559 Berlin, Germany
* Sitz / Registered office: Berlin, HRB 134158 B
* Geschaeftsfuehrer / Managing Director: Harald Welte