Re: [GIT PULL] ring-buffer: Updates for 6.11

[Mathieu Desnoyers <mathieu.desnoyers@efficios.com>]

On 2024-07-19 10:32, Steven Rostedt wrote:
> On Tue, 16 Jul 2024 16:05:26 -0400
> Mathieu Desnoyers <mathieu.desnoyers@efficios.com> wrote:
> 
>> On 2024-07-16 15:51, Steven Rostedt wrote:
>>>
>>>
>>> Linus,
>>>
>>> tracing/ring-buffer: Have persistent buffer across reboots
>>
>> Hi Steven,
>>
>> Perhaps I'm missing something here, but we discussed previously that
>> you would document the fact that users of this feature are expected
>> to run the same kernel before/after reboot.
>>
>> Looking at this PR, I fail to find that documentation, or in fact
>> any documentation at all. Is this something that was overlooked ?
> 
> So I went to update this, and realized there's no place that actually
> mentions anything about this being used across reboots (besides in the
> change logs). The only documentation is in kernel-parameters.txt:
> 
>                          If memory has been reserved (see memmap for x86), the instance
>                          can use that memory:
>                          
>                                  memmap=12M$0x284500000 trace_instance=boot_map@0x284500000:12M
> 
>                          The above will create a "boot_map" instance that uses the physical
>                          memory at 0x284500000 that is 12Megs. The per CPU buffers of that
>                          instance will be split up accordingly.
> 
> I do plan on adding more documentation on the use cases of this, but I
> was planning on doing that in the next merge window when the
> reserve_mem kernel parameter can be used. Right now, we only document
> what it does, and not what it is used for.
> 
> Do you still have an issue with that part missing? No where does it
> mention that this is used across boots. There is a file created in the
> boot mapped instance directory that hints to the usage
> (last_boot_info), but still there's no assumptions made.
> 
> In other words, why document a restriction on something that hasn't
> been documented?

AFAIU the intended use of this feature is to convey trace buffer
data from one kernel to the next across a reboot, which makes it
a whole different/new kind of ABI.

Having no documentation will not stop anyone from using this new
feature and make assumptions about ABI guarantees. I am concerned
that this ABI ends up being defined by accident/misuses rather than
by design if it is merged without documentation.

Very often when I find myself documenting a feature, I look back at
the user-facing result and modify the ABI where it does not make
sense. Merging this ABI without documentation prevents that.

So if you ask my honest opinion there, I would say that merging this
ABI without documentation feels rushed.

Thanks,

Mathieu

-- 
Mathieu Desnoyers
EfficiOS Inc.
https://www.efficios.com