Idea to have qmicli output "parseable" data

Tue Jul 27 20:14:37 UTC 2021

Hey,

> >> I wonder if the error reporting is worth merging separately? This was one of the oddities I had noticed that slightly complicated parsing
> >>
> > Error reports are given in TLVs as any other TLV in the response
> > message. I think that would be the best thing to do also in the JSON
> > output, so that the parsers can expect this TLV to exist ALWAYS in all
> > response messages:
> >
> >   "result": {
> >     "error-status": "0",
> >     "error-code": "0"
> >   },
>
>
> Yes please!
>
> Also remember that in some circumstances there is some "noise", which is kinda error, kinda status,
> kinda data. I'm thinking about when you start a data connection and/or keep a CID open
>
> Perhaps we can get that into the result section and have a separate "data" section?

I think the only special case to consider would be the logic to keep
the CID open; we could add a new "cid-open" field at the same level as
the "result" struct.

>
> > For some of the messages, it's true that qmicli also does some magic
> > here and there, but I believe printing the raw contents of the
> > response in JSON isn't a bad initial approach.
>
>
> I'm indifferent, but if you are asking me, I would say lets try and have the JSON output be
> identical to the text output, ie it's just a formatting concern?
>

It's not only a formatting concern. Doing it without any format can be
done without further knowledge of what is being printed, and the
current logic I implemented already does that mostly. Adding format
means that we may need to e.g. "post-process" the JSON that we got
from the generated code. Not sure I like the idea of post-processing,
not sure.

>
> >> I wonder if we can't go a further up and consider the individual commands to be knocking some output map alike structure into shape, then the output is just a structure we either output as text, or output as json as we prefer? I wonder at the moment if the JSON and test outputs would be so similar?
> > That's basically what we did in ModemManager, yes, see
> > https://gitlab.freedesktop.org/mobile-broadband/ModemManager/-/blob/master/cli/mmcli-output.c
> > Even the "human pretty output" is generated by the output engine.
>
>
> ^This! Lets do this!
>
> I waiting, but not hearing cries that we shouldn't change the output of qmicli too much..? I wonder
> if someone has a vote that we fork qmicli into a sort of new utility, deprecate the old one and
> steal something like the mmcli formatter here to bolt onto the qmicli base?
>

There is absolute no guarantee of stability for the qmicli output; it
has never been considered API. If anyone was attempting to parse it
and the parsing now breaks, we're at least providing a more robust way
of doing it if we ship the JSON output at the same time as we change
the human pretty output. I wouldn't be concerned about this really, no
need to fork anything.

>
>
> >> How did you propose to handle the cases where there is both a value for a key and a sub value? For example in "--nas-get-serving-system" we have
> >>
> >>     Radio interfaces: '1'
> >>         [0]: 'lte'
> >>
> >> What I did was to store the '1" in a "_value" key under the "Radio interfaces" key
> >>
> > Really, I don't remember what was done for every type. What I did was
> > to improve the qmi-codegen output to also support generating the JSON
> > output, it's very much the same as the printable message outputs we
> > have when traces are enabled in libqmi, the very same idea. Arrays are
> > converted into JSON arrays, complex types are converted into JSON
> > structs, and so on.
> >
> >> I also provided some heuristics to parse keys like:
> >>
> >>     3GPP daylight saving time adjustment: '1' hours
> >>
> >> into ['1', 'hours']
> >>
> > That would be too much IMO. The original idea was that the JSON output
> > in libqmi should print raw values as received from the modem. But
> > then, a lot of fields in QMI messages have "additional" formatting
> > required, as e.g. with the signal quality values in several messages.
> > For example, the SNR for LTE in "NAS Get Signal Info" is not given in
> > dB directly, you need to divide the given value by 10 in order to get
> > the dBs. What should the JSON output report in this case? the original
> > value or the one already processed to get dBs? It's tricky, and it's
> > really a lot of work, but it may be a good idea to give the processed
> > values also in the JSON output, for simplicity (i.e. we do it once in
> > libqmi, instead of N times by N different users). My original
> > implementation would need to be changed a lot to support that I'm
> > afraid.
>
>
> I'm not sure what is feasible within the constraints of the original data type? In my head we:
>
> - get the original data
>
> - massage it for the benefit of sensible consumption
>
> - lightly format it as part of the output
>

At which time do we do the last step? The qmi-codegen logic currently
can build the JSON output on raw TLV data. Do we post-process that
JSON to provide format to some of the fields, or do we embed that in
the qmi-codegen logic as well? It's not trivial any of the solutions I
think.

>
> So I am ignorant of the details, but I would be wondering if we could tag values with a "type", such
> that a generic output formatter could do some scaling and apply a suffix (eg -23dB) in the case of a
> textual format, but perhaps do something slightly different in the case of the json/xml output, eg
> ["-23", "dB"]
>
> What options are simple in this space?
>
> I think the goal would be a small number of consistent modifications which add value, rather than
> the current situation of micro massaging specific API outputs (possibly in an inconsistent manner?).
> Does this sort of thing exist in mmcli?
>

The mmcli case is not completely equivalent to this one. The amount of
fields reported by mmcli is small compared to the ton of different
TLVs we may have reported by qmicli. I think that from mmcli we could
take the big picture of what could be done (a single output generator
logic that switches between formats depending on what the user
requested); but then the qmicli related implementation must be highly
based on qmi-codegen generating the code.

> How many people are going to moan if qmicli has a dramatic shakeup in the normal textual output? How
> would such a theoretical shakeup be best handled? (Suggestion above to create a new utility to give
> people time to migrate?)
>

As said, the output format of qmicli has never been considered API, so
if someone did that, it's kind of wrong already. I'm fine changing the
qmicli output format if we at the same time provide the JSON (and/or
key-value pairs as in mmcli) output format.

> I do think there would be quite a lot of value in going through a broadly similar output process for
> plain text and json?
>

Yes.

> As you say, there is a lot of typing if we don't get this planned out in advance - lets get this right
>
> Further discussion appreciated?
>

You know what scares me most? The amount of special things we may need
to do with the different fields. The SNR division by 10 is just 1
single example. There are more complex things that we would also need
to do, because we're doing them already in the human output; e.g.
calls to qmi_nas_read_string_from_plmn_encoded_array() where
appropriate, different print operations based on the contents of a
given field... The things that we could do are so many, that in my
mind, the only way forward would be to not even attempt to do them as
part of qmi-codegen, and instead think in the post-processing phase
applicable to all output types. It's something that we'll need to do
one by one for each qmicli action...

Is there any company out there that would benefit from this feature
and would like to hire me to do it? If so, let me know, I would
definitely love to work on this :)

-- 
Aleksander
https://aleksander.es