The 'show online-help' produces XML output with <node id="..."> ids. We
reference those from the osmo-gsm-manuals.
Instead of numeric IDs coming from internal code, rather use a human-readable
node ID -- referencing id='config-msc' is much easier than referencing id='23'.
Add a char name[] to struct cmd_node, to hold this name. This may be provided
upon struct definition.
Since callers of the VTY API so far don't have a name yet, we would need to add
names everywhere to get meaningful node IDs. There is a way to get node ID
names without touching dependent code:
My first idea was to find out which command entered the node, i.e. command
'msc' enters the MSC_NODE. But it is impossible to derive which command entered
which node from data structs, it's hidden in the vty command definition.
But in fact all (TM) known API callers indeed provide a prompt string that
contains a logical and human readable string name. Thus, if the name is unset
in the struct, parse the prompt string and strip all "weird" characters to
obtain a node name from that. We can still set names later on, but for now will
have meaningful node IDs (e.g. 'config-msc' from '%s(config-msc)# ') without
touching any dependent code.
When VTY nodes get identical node names, which is quite possible, the XML
export de-dups these by appending _2, _3,... suffixes. The first occurence is
called e.g. 'name', the second 'name_2', then 'name_3', and so forth.
If a node has no name (even after parsing the prompt), it will be named merely
by the suffix. The first empty node will become id='_1', then '_2', '_3', and
so forth. This happens for nodes like VIEW_NODE or AUTH_NODE.
If this is merged, we need to adjust the references in osmo-gsm-manuals.git.
This can happen in our own time though, because we manually create the vty
reference xml and copy it to the osmo-gsm-manuals.git and then update the
references from the vty_additions.xml. This anyway has to happen because
currently the references tend to be hopelessly out of sync anyway, placing
comments at wildly unrelated VTY commands.
Change-Id: I8fa555570268b231c5e01727c661da92fad265de
The 'show online-help' produces XML output with <node id="..."> ids. We
reference those from the osmo-gsm-manuals, but until now, these ids fall out of
sync when the amount of VTY nodes changes.
Change these ids to use the internal node ID constant (as in enum bsc_vty_node)
instead of a simple counter.
If this is merged, we need to adjust the references in osmo-gsm-manuals.git.
Change-Id: Ib07fb9d9106e19f5be6539493e82b5d5991f8bc2
The recent exit-by-indent patch breaks a VTY case where a node is entered but
directly followed by a sibling or ancestor without listing any child nodes.
Regression introduced by I24cbb3f6de111f2d31110c3c484c066f1153aac9.
An example is a common usage in osmo-bts, where 'phy N' / 'instance N' is a
parent node that is commonly left empty:
phy 0
instance 0
bts 0
band 1800
Before this patch, this case produces the error:
There is no such command.
Error occurred during reading the below line:
bts 0
Fix indentation parsing logic in command.c to accomodate this case.
Add a unit test for empty parent node.
Change-Id: Ia0880a17ae55accb092ae8585cc3a1bec9986891
Note: This will break users' config files if they do not use consistent
indenting. (see below for a definition of "consistent".)
When reading VTY commands from a file, use indenting as means to implicitly
exit child nodes. Do not look for commands in the parent node implicitly.
The VTY so far implies 'exit' commands if a VTY line cannot be parsed on the
current node, but succeeds on the parent node. That is the mechanism by which
our VTY config files do not need 'exit' at the end of each child node.
We've hit problems with this in the following scenarios, which will show
improved user experience after this patch:
*) When both a parent and its child node have commands with identical names:
cs7 instace 0
point-code 1.2.3
sccp-address osmo-msc
point-code 0.0.1
If I put the parent's command below the child, it is still interpreted in the
context of the child node:
cs7 instace 0
sccp-address osmo-msc
point-code 0.0.1
point-code 1.2.3
Though the indenting lets me assume I am setting the cs7 instance's global PC
to 1.2.3, I'm actually overwriting osmo-msc's PC with 1.2.3 and discarding the
0.0.1.
*) When a software change moves a VTY command from a child to a parent. Say
'timezone' moved from 'bts' to 'network' level:
network
timezone 1 2
Say a user still has an old config file with 'timezone' on the child level:
network
bts 0
timezone 1 2
trx 0
The user would expect an error message that 'timezone' is invalid on the 'bts'
level. Instead, the VTY finds the parent node's 'timezone', steps out of 'bts'
to the 'network' level, and instead says that the 'trx' command does not exist.
Format:
Consistent means that two adjacent indenting lines have the exact
same indenting characters for the common length:
Weird mix if you ask me, but correct and consistent:
ROOT
<space>PARENT
<space><tab><space>CHILD
<space><tab><space><tab><tab>GRANDCHILD
<space><tab><space><tab><tab>GRANDCHILD2
<space>SIBLING
Inconsistent:
ROOT
<space>PARENT
<tab><space>CHILD
<space><space><tab>GRANDCHILD
<space><tab><tab>GRANDCHILD2
<tab>SIBLING
Also, when going back to a parent level, the exact same indenting must be used
as before in that node:
Incorrect:
ROOT
<tab>PARENT
<tab><tab><tab>CHILD
<tab><tab>SIBLING
As not really intended side effect, it is also permitted to indent the entire
file starting from the root level. We could guard against it but there's no
harm:
Correct and consistent:
<tab>ROOT
<tab><tab>PARENT
<tab><tab><tab><tab>CHILD
<tab><tab>SIBLING
Implementation:
Track parent nodes state: whenever a command enters a child node, push a parent
node onto an llist to remember the exact indentation characters used for that
level.
As soon as the first line on a child node is parsed, remember this new
indentation (which must have a longer strlen() than its parent level) to apply
to all remaining child siblings and grandchildren.
If the amount of spaces that indent a following VTY command are less than this
expected indentation, call vty_go_parent() until it matches up.
At any level, if the common length of indentation characters mismatch, abort
parsing in error.
Transitions to child node are spread across VTY implementations and are hard to
change. But transitions to the parent node are all handled by vty_go_parent().
By popping a parent from the list of parents in vty_go_parent(), we can also
detect that a command has changed the node without changing the parent, hence
it must have stepped into a child node, and we can push a parent frame.
The behavior on the interactive telnet VTY remains unchanged.
Change-Id: I24cbb3f6de111f2d31110c3c484c066f1153aac9
For interactive telnet VTY, remove the implicit move up to the parent node when
a command did not succeed on the current node level.
When reading config files, this behavior was useful to allow skipping explicit
'exit' commands. (A different patch deals with that.)
In the telnet VTY, this behavior was never necessary. Explicit 'exit' commands
can move to the parent node, and typically uninformed users expect to require
that.
On a telnet VTY, counting indents like for reading config files is not an
option: a user will always type from the first column or may paste some leading
spaces without intended meaning.
After this patch, it is thus no longer possible to paste a complete config
across several node levels directly to a telnet session, unless it contains
'exit' commands.
Change-Id: Id73cba2dd34676bad8a130e9c45e67a272f19588
Considering the various styles and implications found in the sources, edit
scores of files to follow the same API doc guidelines around the doxygen
grouping and the \file tag.
Many files now show a short description in the generated API doc that was so
far only available as C comment.
The guidelines and reasoning behind it is documented at
https://osmocom.org/projects/cellular-infrastructure/wiki/Guidelines_for_API_documentation
In some instances, remove file comments and add to the corresponding group
instead, to be shared among several files (e.g. bitvec).
Change-Id: Ifa70e77e90462b5eb2b0457c70fd25275910c72b
Especially for short descriptions, it is annoying to have to type \brief for
every single API doc.
Drop all \brief and enable the AUTOBRIEF feature of doxygen, which always takes
the first sentence of an API doc as the brief description.
Change-Id: I11a8a821b065a128108641a2a63fb5a2b1916e87
It's a pity that even with this patch we still are fare away from having
the whole API documented. However, at least we have a more solid
foundation. Updates not only extend the documentation, but also make
sure it is rendered properly in the doxygen HTML.
Change-Id: I1344bd1a6869fb00de7c1899a8db93bba9bafce3
When the caller installs two identical commands at a given VTY node, the
result is that neither of the two commands can ever be executed: The VTY
would always complain about "Ambiguous command.". Let's fail fast at
program start when two identical commands are intalled.
Change-Id: I85ff4640ebb3d8b75a6a9ab5d2f668edb5b7189e
For each counter group a ascii doc table is generated
containing all single counter with a reference to a section to
add additional information to the counter
Change-Id: Ia8af883167e5ee631059299b107ea83c8bbffdfb
Reviewed-on: https://gerrit.osmocom.org/70
Reviewed-by: Harald Welte <laforge@gnumonks.org>
Tested-by: Harald Welte <laforge@gnumonks.org>
We are mixing enums and hope that no short-enums are used. This
is leading to a lot compiler warnings generated by clang. Change
the API to work with integers.
Porting:
The go_parent_cb implementations in the applications need to be
fixed. The API change leads to a compile time warning.
Fixes:
abis_om2000_vty.c:46:2: warning: implicit conversion from enumeration type 'enum bsc_vty_node' to
different enumeration type 'enum node_type' [-Wenum-conversion]
OM2K_NODE,
^~~~~~~~~
For the BSC/NITB application we see that people modify the band
without modifying the ARFCN. This creates an unbootable config.
Using the new hook the BSC/NITB can check if the config is
consistent and prevent the config file being written.
Related: SYS#739
This patch removes an assertion of node > CONFIG_NODE and changes
the function to handle all nodes properly.
For the sake of completeness, the generic 'exit' command
implementation is extended to work properly with all nodes, too.
This adds the vty_install_default() function that is basically the
install_default() function plus the registration of the commands
'exit' and 'end'. The latter is only provided in subnodes of
ENABLED_NODE and CONFIG_NONE.
The VTY test program is extended to check these commands.
Ticket: OW#952
These routines were not freeing vectors used for the lookup. On
review it is fixing another path not detected by coverity.
The danger is a double free in tab completion now. It is difficult
to test this.
Fixes: Coverity CID 23037, CID 23038
This hides HIDDEN or DEPRECATED commands from showing up when the
full list of commands is inquired with '?' at any given point in the
command tree. Only if the hidden/deprecated command is already typed
in partially, then it will still tab-complete.
This is essentially http://patchwork.diac24.net/patch/271/ forward
ported to libosmovty
Original-by: Paul Jakma <paul@quagga.net>
Signed-off-by: Sylvain Munaut <tnt@246tNt.com>
When building the doxygen documentation do not remove the other
VTY documentation files in the doc/vty folder. Create a command
that can be installed to dump all nodes and commands as XML on
the given VTY. Create a schema for the XML file and a XSL-T script
that can merge the generated file with additional information.
This patch moves all GSM-specific definitions to include/osmocom/gsm.
Moreover, the headers in include/osmocore/ have been moved to
include/osmocom/core.
This has been proposed by Harald Welte and Sylvain Munaunt.
Tested with `make distcheck'.
Signed-off-by: Pablo Neira Ayuso <pablo@gnumonks.org>
The method should be renamed to is child of config node
as it was comparing if vty->node > CONFIG_NODE. This is
fixing an assert in go_to_parent as we tried to find a
parent for the CONFIG_NODE.
Neels Hofmeyr
Neels Hofmeyr
Harald Welte
Sylvain Munaut