[PATCH drm-next v4 00/14] [RFC] DRM GPUVA Manager & Nouveau VM_BIND UAPI

[Donald Robson]

On Tue, 2023-06-13 at 16:20 +0200, Danilo Krummrich wrote:

> I'm definitely up improving the existing documentation. Anything in 
> particular you think should be described in more detail?
> 
> - Danilo

Hi Danilo,

As I said, with inexperience it's possible I missed what I was
looking for in the existing documentation, which is highly detailed
in regard to how it deals with operations, but usage was where I fell
down.

If I understand there are three ways to use this, which are:
1) Using drm_gpuva_insert() and drm_gpuva_remove() directly using
   stack va objects.
2) Using drm_gpuva_insert() and drm_gpuva_remove() in a callback
   context, after having created ops lists using
   drm_gpuva_sm_[un]map_ops_create().
3) Using drm_gpuva_[un]map() in callback context after having
   prealloced a node and va objects for map/remap function use,
   which must be forwarded in as the 'priv' argument to
   drm_gpuva_sm_[un]map().

The first of these is pretty self-explanatory.  The second was also
fairly easy to understand, it has an example in your own driver, and
since it takes care of allocs in drm_gpuva_sm_map_ops_create() it
leads to pretty clean code too.

The third case, which I am using in the new PowerVR driver did not
have an example of usage and the approach is quite different to 2)
in that you have to prealloc everything explicitly.  I didn't realise
this, so it led to a fair amount of frustration.

I think if you're willing, it would help inexperienced implementers a
lot if there were some brief 'how to' snippets for each of the three
use cases.

Thanks,
Donald