[PATCH 18/18] doc: Update logging documentation

[Heinrich Schuchardt]

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.

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

Something like like https://man7.org/linux/man-pages/man1/git-commit.1.html.

Best regards

Heinrich

>
>>
>> Users will need a complete description of the log command with all
>> parameters.
>>
>> Best regards
>>
>> Heinrich
>>
>>> +
>>> +To view active filters, use the 'log filter-list' command. Some example output
>>> +is::
>>> +
>>> +    => log filter-list
>>> +    num policy level           categories files
>>> +      0   deny <=IO                   spi
>>> +      1  allow <=DEBUG
>>> +
>>> +Note that filters are processed in-order from top to bottom, not in the order of
>>> +their filter number. Filters are added to the top of the list if they deny when
>>> +they match, and to the bottom if they allow when they match. For more
>>> +information, consult the usage of the 'log' command, by running 'help log'.
>
> Here is my suggestion of where to find a complete list of options.
>
> --Sean
>
>>>
>>>  Logging statements
>>>  ------------------
>>> @@ -259,8 +286,6 @@ Add a way to browse log records
>>>
>>>  Add a way to record log records for browsing using an external tool
>>>
>>> -Add commands to add and remove filters
>>> -
>>>  Add commands to add and remove log devices
>>>
>>>  Allow sharing of printf format strings in log records to reduce storage size
>>> @@ -268,10 +293,6 @@ for large numbers of log records
>>>
>>>  Add a command-line option to sandbox to set the default logging level
>>>
>>> -Convert core driver model code to use logging
>>> -
>>> -Convert uclasses to use logging with the correct category
>>> -
>>>  Consider making log() calls emit an automatic newline, perhaps with a logn()
>>>  function to avoid that
>>>
>>> @@ -282,9 +303,6 @@ number dropped due to them being generated before the log system was ready.
>>>
>>>  Add a printf() format string pragma so that log statements are checked properly
>>>
>>> -Enhance the log console driver to show level / category / file / line
>>> -information
>>> -
>>>  Add a command to add new log records and delete existing records.
>>>
>>>  Provide additional log() functions - e.g. logc() to specify the category
>>>
>>
>