[PATCH v1 12/14] drm/xe/uapi: Add examples of user space code

[Rodrigo Vivi]

On Thu, Dec 07, 2023 at 01:50:07PM +0000, Francois Dugast wrote:
> Complete the documentation of some structs by adding functional
> examples of user space code. Those examples are intentionally kept
> very simple. Put together, they provide a foundation for a minimal
> application that executes a job using the Xe driver.
> 
> Signed-off-by: Francois Dugast <francois.dugast at intel.com>
> ---
>  include/uapi/drm/xe_drm.h | 84 +++++++++++++++++++++++++++++++++++++++
>  1 file changed, 84 insertions(+)
> 
> diff --git a/include/uapi/drm/xe_drm.h b/include/uapi/drm/xe_drm.h
> index b5117bc1f13c..6811a1c96078 100644
> --- a/include/uapi/drm/xe_drm.h
> +++ b/include/uapi/drm/xe_drm.h
> @@ -962,6 +962,30 @@ struct drm_xe_vm_bind_op {
>  
>  /**
>   * struct drm_xe_vm_bind - Input of &DRM_IOCTL_XE_VM_BIND
> + *
> + * Below is an example of a minimal use of @drm_xe_vm_bind to
> + * asynchronously bind the buffer `data` at address `BIND_ADDRESS` to
> + * illustrate `userptr`. It can be synchronized by using the example
> + * provided for @drm_xe_sync.
> + *
> + * .. code-block:: C
> + *
> + *     data = aligned_alloc(ALIGNMENT, BO_SIZE);
> + *     struct drm_xe_vm_bind bind = {
> + *         .vm_id = vm,
> + *         .num_binds = 1,
> + *         .bind.obj = 0,
> + *         .bind.obj_offset = to_user_pointer(data),
> + *         .bind.range = BO_SIZE,
> + *         .bind.addr = BIND_ADDRESS,
> + *         .bind.op = DRM_XE_VM_BIND_OP_MAP_USERPTR,
> + *         .bind.flags = DRM_XE_VM_BIND_FLAG_ASYNC,
> + *         .num_syncs = 1,
> + *         .syncs = &sync,
> + *         .exec_queue_id = 0,
> + *     };
> + *     ioctl(fd, DRM_IOCTL_XE_VM_BIND, &bind);
> + *
>   */
>  struct drm_xe_vm_bind {
>  	/** @extensions: Pointer to the first extension struct, if any */
> @@ -1023,6 +1047,25 @@ struct drm_xe_vm_bind {
>  
>  /**
>   * struct drm_xe_exec_queue_create - Input of &DRM_IOCTL_XE_EXEC_QUEUE_CREATE
> + *
> + * The example below shows how to use @drm_xe_exec_queue_create to create
> + * a simple exec_queue (no parallel submission) of class
> + * &DRM_XE_ENGINE_CLASS_RENDER.
> + *
> + * .. code-block:: C
> + *
> + *     struct drm_xe_engine_class_instance instance = {
> + *         .engine_class = DRM_XE_ENGINE_CLASS_RENDER,
> + *     };
> + *     struct drm_xe_exec_queue_create exec_queue_create = {
> + *          .extensions = 0,
> + *          .vm_id = vm,
> + *          .num_bb_per_exec = 1,
> + *          .num_eng_per_bb = 1,
> + *          .instances = to_user_pointer(&instance),
> + *     };
> + *     ioctl(fd, DRM_IOCTL_XE_EXEC_QUEUE_CREATE, &exec_queue_create);
> + *
>   */
>  struct drm_xe_exec_queue_create {
>  #define DRM_XE_EXEC_QUEUE_EXTENSION_SET_PROPERTY		0
> @@ -1114,6 +1157,30 @@ struct drm_xe_exec_queue_get_property {
>   *
>   * and the @flags can be:
>   *  - %DRM_XE_SYNC_FLAG_SIGNAL
> + *
> + * A minimal use of @drm_xe_sync looks like this:
> + *
> + * .. code-block:: C
> + *
> + *     struct drm_xe_sync sync = {
> + *         .flags = DRM_XE_SYNC_FLAG_SIGNAL,
> + *         .type = DRM_XE_SYNC_TYPE_SYNCOBJ,
> + *     };
> + *     struct drm_syncobj_create syncobj_create = { 0 };
> + *     ioctl(fd, DRM_IOCTL_SYNCOBJ_CREATE, &syncobj_create);
> + *     sync.handle = syncobj_create.handle;
> + *         ...
> + *         use of &sync in drm_xe_exec or drm_xe_vm_bind
> + *         ...
> + *     struct drm_syncobj_wait wait = {
> + *         .handles = &sync.handle,
> + *         .timeout_nsec = INT64_MAX,
> + *         .count_handles = 1,
> + *         .flags = 0,
> + *         .first_signaled = 0,
> + *         .pad = 0,
> + *     };
> + *     ioctl(fd, DRM_IOCTL_SYNCOBJ_WAIT, &wait);
>   */
>  struct drm_xe_sync {
>  	/** @extensions: Pointer to the first extension struct, if any */
> @@ -1156,6 +1223,23 @@ struct drm_xe_sync {
>  
>  /**
>   * struct drm_xe_exec - Input of &DRM_IOCTL_XE_EXEC
> + *
> + * This is an example to use @drm_xe_exec for execution of the object
> + * at BIND_ADDRESS (see example in @drm_xe_vm_bind) by an exec_queue
> + * (see example in @drm_xe_exec_queue_create). It can be synchronized
> + * by using the example provided for @drm_xe_sync.
> + *
> + * .. code-block:: C
> + *
> + *     struct drm_xe_exec exec = {
> + *         .exec_queue_id = exec_queue,

one thing that I believe we are missing on these ioclt examples is how
to bridge them and be more explicit that the exec_queue id here came
as output of the exec_queue_create.

As well as the 'vm' items used on the above cases. But anyway, I believe
that that could be done later and this is already an improvement in the
doc. Ideally uapi docs should have examples and be self-sufficient to
any new UMD developer working with these entries. So, this series
is already a big step towards that, so:

Reviewed-by: Rodrigo Vivi <rodrigo.vivi at intel.com>

> + *         .syncs = &sync,
> + *         .num_syncs = 1,
> + *         .address = BIND_ADDRESS,
> + *         .num_batch_buffer = 1,
> + *     };
> + *     ioctl(fd, DRM_IOCTL_XE_EXEC, &exec);
> + *
>   */
>  struct drm_xe_exec {
>  	/** @extensions: Pointer to the first extension struct, if any */
> -- 
> 2.34.1
>