[PATCH v6 6/6] drm/doc: Define KMS atomic state set

[André Almeida]

On 10/16/23 16:52, Pekka Paalanen wrote:
> On Mon, 16 Oct 2023 15:42:16 +0200
> André Almeida <andrealmeid at igalia.com> wrote:
>
>> Hi Pekka,
>>
>> On 10/16/23 14:18, Pekka Paalanen wrote:
>>> On Mon, 16 Oct 2023 12:52:32 +0200
>>> André Almeida <andrealmeid at igalia.com> wrote:
>>>   
>>>> Hi Michel,
>>>>
>>>> On 8/17/23 12:37, Michel Dänzer wrote:
>>>>> On 8/15/23 20:57, André Almeida wrote:
>>>>>> From: Pekka Paalanen <pekka.paalanen at collabora.com>
>>>>>>
>>>>>> Specify how the atomic state is maintained between userspace and
>>>>>> kernel, plus the special case for async flips.
>>>>>>
>>>>>> Signed-off-by: Pekka Paalanen <pekka.paalanen at collabora.com>
>>>>>> Signed-off-by: André Almeida <andrealmeid at igalia.com>
>>>>> [...]
>>>>>      
>>>>>> +An atomic commit with the flag DRM_MODE_PAGE_FLIP_ASYNC is allowed to
>>>>>> +effectively change only the FB_ID property on any planes. No-operation changes
>>>>>> +are ignored as always. [...]
>>>>> During the hackfest in Brno, it was mentioned that a commit which re-sets the same FB_ID could actually have an effect with VRR: It could trigger scanout of the next frame before vertical blank has reached its maximum duration. Some kind of mechanism is required for this in order to allow user space to perform low frame rate compensation.
>>>>>      
>>>> Xaver tested this hypothesis in a flipping the same fb in a VRR monitor
>>>> and it worked as expected, so this shouldn't be a concern.
>>> Right, so it must have some effect. It cannot be simply ignored like in
>>> the proposed doc wording. Do we special-case re-setting the same FB_ID
>>> as "not a no-op" or "not ignored" or some other way?
>> There's an effect in the refresh rate, the image won't change but it
>> will report that a flip had happened asynchronously so the reported
>> framerate will be increased. Maybe an additional wording could be like:
>>
>> Flipping to the same FB_ID will result in a immediate flip as if it was
>> changing to a different one, with no effect on the image but effecting
>> the reported frame rate.
> Re-setting FB_ID to its current value is a special case regardless of
> PAGE_FLIP_ASYNC, is it not?
>
> So it should be called out somewhere that applies regardless of
> PAGE_FLIP_ASYNC. Maybe to the end of the earlier paragraph:
>
>> +The changes recorded in an atomic commit apply on top the current KMS state in
>> +the kernel. Hence, the complete new KMS state is the complete old KMS state with
>> +the committed property settings done on top. The kernel will try to avoid
>> +no-operation changes, so it is safe for userspace to send redundant property
>> +settings.  However, not every situation allows for no-op changes, due to the
>> +need to acquire locks for some attributes. Userspace needs to be aware that some
>> +redundant information might result in oversynchronization issues.  No-operation
>> +changes do not count towards actually needed changes, e.g.  setting MODE_ID to a
>> +different blob with identical contents as the current KMS state shall not be a
>> +modeset on its own.
> +As a special exception for VRR needs, explicitly setting FB_ID to its
> +current value is not a no-op.
>
> Would that work?

I liked this suggestion, thanks! I'll wrap up a v7

> I'd like to try to avoid being more specific about what it does
> exactly, because that's not the topic here. Such things can be
> documented with the property itself. This is a summary of what is or is
> not a no-op or a modeset.
>
>
> Thanks,
> pq