Re: [PATCH 2/2] dma-buf: Document how exporters and importers agree on mapping lifetime

[Christian König]

On 8/26/26 16:02, Leon Romanovsky wrote:
...
>>>>> + *
>>>>> + * Pinned flow:
>>>>> + *
>>>>> + * - Exporter: implement &dma_buf_ops.pin and &dma_buf_ops.unpin to hold the
>>>>> + *   storage still on request. An exporter whose storage never moves implements
>>>>> + *   neither, and dma_buf_pin() then succeeds on its own. An exporter which
>>>>> + *   refuses to be pinned implements &dma_buf_ops.pin and fails it.
>>>>> + * - Importer: nothing more. The mapping stays valid until it unmaps.
>>>>> + *
>>>>> + * Revoked flow:
>>>>> + *
>>>>> + * - Exporter: answer dma_buf_pin() as above. Call
>>>>> + *   dma_buf_invalidate_mappings() when the storage goes away and fail
>>>>> + *   &dma_buf_ops.map_dma_buf while it is gone. The two waits which complete a
>>>>> + *   revocation are described in dma_buf_invalidate_mappings().
>>>>> + * - Importer: &dma_buf_attach_ops.invalidate_mappings has to unmap within
>>>>> + *   bounded time and drop the pin.
>>>>> + *
>>>>> + * Movable flow:
>>>>> + *
>>>>> + * - Exporter: call dma_buf_invalidate_mappings() before each move, then wait
>>>>> + *   for the &dma_buf.resv fences. &dma_buf_ops.pin and &dma_buf_ops.unpin play
>>>>> + *   no part here.
>>>>> + * - Importer: hold no pin. &dma_buf_attach_ops.invalidate_mappings drops the
>>>>> + *   cached mapping and has to lead to dma_buf_unmap_attachment() within
>>>>> + *   bounded time. It need not stop the hardware, because access runs until the
>>>>> + *   importer's &dma_buf.resv fences retire. Map again before the next DMA.
>>>>
>>>> That is also not really correct. Those flows are not separated like this.
>>>
>>> How will you split them?
>>
>> Well you don't. Exporters and importers can have a much wider variety of use cases.
>>
>> When the importer doesn't give an invalidation callback the framework will call pin/unpin when the attachment is mapped/unmapped. That is just a service of the framework to make importers simpler.
>>
>> But it is perfectly possible that an importer which implements the invalidation callback calls pin/unpin manually later on. This for example happens on display scanout when an invalidation would cause garbage on the screen when the buffer is moved.
>>
>> But even after an importer called pin it is possible that the invalidation callback is called in case of a hot remove. Using our example of display scanout once more it is probably better to stop displaying anything then keeping the resources allocated until userspace realizes that the export is not there any more.
>>
>> The revoke flow is then basically just a special case of hot remove. The only difference is that userspace invokes it instead of an user pulling a cable.
> 
> OK, let me add some context on how this split came about and why I am
> trying to document it.
> 
> Several people approached me offline because they need to implement an
> importer that supports both revoke and movable flows. These require
> completely different implementations in the driver internals.

Thanks, that at least helps me understand the goal.

> So, to answer the question, we need to document how these flows are
> identified and how they differ.

Mhm, that's the point I don't think they differ that much.

Completely revoking is just a special case of moving the backing store to an inaccessible place and not making it accessible again on the next map call.

> Naturally, they asked AI first, but all frontier LLMs gave them completely
> incorrect answers.
> 
> With that goal in mind, could you please help document the dma-buf
> lifetime model? "Everything is optional" sounds great, but is quite
> misleading.

Oh, good question I have no idea how to approach that.

Regards,
Christian.

> 
> Thanks