[PATCH 18/18] doc: Update logging documentation

[Sean Anderson]

On 10/6/20 5:28 PM, Heinrich Schuchardt wrote:
> On 10/6/20 10:38 PM, Sean Anderson wrote:
>> On 10/6/20 4:34 PM, Heinrich Schuchardt wrote:
>>> On 10/6/20 9:16 PM, Sean Anderson wrote:
>>>> This updates logging documentation with some examples of the new commands
>>>> added in the previous commits. It also removes some items from the to-do
>>>> list which have been implemented.
>>>>
>>>> Signed-off-by: Sean Anderson <seanga2 at gmail.com>
>>>> ---
>>>>
>>>>  doc/develop/logging.rst | 42 +++++++++++++++++++++++++++++------------
>>>>  1 file changed, 30 insertions(+), 12 deletions(-)
>>>>
>>>> diff --git a/doc/develop/logging.rst b/doc/develop/logging.rst
>>>> index 6a22062073..8b6237f829 100644
>>>> --- a/doc/develop/logging.rst
>>>> +++ b/doc/develop/logging.rst
>>>> @@ -174,18 +174,45 @@ fields are present, but not the field order.
>>>>  Filters
>>>>  -------
>>>>
>>>> -Filters are attached to log drivers to control what those drivers emit. Only
>>>> -records that pass through the filter make it to the driver.
>>>> +Filters are attached to log drivers to control what those drivers emit. FIlters
>>>> +can either allow or deny a log message when they match it. Only records which
>>>> +are allowed by a filter make it to the driver.
>>>>
>>>>  Filters can be based on several criteria:
>>>>
>>>> -* maximum log level
>>>> +* minimum or maximum log level
>>>>  * in a set of categories
>>>>  * in a set of files
>>>>
>>>>  If no filters are attached to a driver then a default filter is used, which
>>>>  limits output to records with a level less than CONFIG_MAX_LOG_LEVEL.
>>>>
>>>> +Adding Filters
>>>> +~~~~~~~~~~~~~~
>>>> +
>>>> +To add new filters at runtime, use the 'log filter-add' command. For example, to
>>>> +filter messages from the SPI subsystem, run::
>>>
>>> Does "filter" mean I see only messages from SPI or does this mean I see
>>> no messages from SPI? If you mean suppress, please, use that word or
>>> something similar.
>>
>> Ok.
>>
>>>
>>>> +
>>>> +    log filter-add -D -c spi
>>>> +
>>>> +You will also need to allow everything else to emit messages (because the
>>>> +default filter no longer applies)::
>>>> +
>>>> +    log filter-add -A -l debug
>>>
>>> Thank you for starting the documenation.
>>>
>>> Unfortunately after reading the lines above I have no clue what the
>>> meaning of -D -A -c -l are.
>>
>> These options are currently documented in the help text for log. Should
>> they be added here? I am concerned that duplicating documentation will
>> result in drift over time.
> 
> If I look at https://u-boot.readthedocs.io/en/latest/, it is currently
> far from what users needs.
> 
> The chapter "Develop U-Boot" seems to be the wrong place for describing
> commands.

Well, I think that this really depends on who the log subsystem is
intended for. From what I can tell, it was originally intended as an aid
to developers. Some users are starting to make use of it (e.g. via
syslog), but most users probably have CONFIG_LOG disabled to reduce boot
times. The commands I have added are also developer-oriented. While
users certainly could use the new filter flags, they would probably want
to create their filters very early (e.g. as soon as the log subsystem
comes up). Going forward, this may not be the best place for log
documentation.

> 
> We need a chapter in our online documentation documenting all commands
> in enough detail for a rookie to understand how to use them.

Yes, I agree. If possible, they should be generated from U-Boot source
files, so that the documentation can live close to the commands (and so
existing help strings could be used). I'm not really sure what the best
way to go about that is. Perhaps kerneldoc could be (ab)used? In any
case, such a change is outside the scope of this patch.

--Sean