PowerVR UAPI

PowerVR UAPI와 object array

이 절의 source는 `include/uapi/drm/pvr_drm.h`입니다. PowerVR UAPI 전체 문서와 object array 표현을 구성하는 `drm_pvr_obj_array`, `DRM_PVR_OBJ_ARRAY` identifier를 연결합니다.

Object array abstraction은 여러 UAPI object를 pointer·count 형태로 전달하는 공통 표현을 문서화하는 출발점이며, 뒤의 query와 submission argument에서 사용하는 구조를 이해하는 데 필요합니다.

====
UAPI
====
The sources associated with this section can be found in ``pvr_drm.h``.

.. kernel-doc:: include/uapi/drm/pvr_drm.h
   :doc: PowerVR UAPI

OBJECT ARRAYS
=============
.. kernel-doc:: include/uapi/drm/pvr_drm.h
   :identifiers: drm_pvr_obj_array

.. kernel-doc:: include/uapi/drm/pvr_drm.h
   :identifiers: DRM_PVR_OBJ_ARRAY

IOCTLS

IOCTL dispatch와 DEV_QUERY

IOCTL 상위 절은 PowerVR IOCTL interface와 `PVR_IOCTL` identifier를 문서화합니다.

`DEV_QUERY`는 device capability와 runtime state를 조회하는 interface입니다. `drm_pvr_dev_query` command, 공통 argument `drm_pvr_ioctl_dev_query_args`, query result structure를 각 identifier group으로 나눕니다.

GPU·runtime·hardware render target 정보는 `drm_pvr_dev_query_gpu_info`, `drm_pvr_dev_query_runtime_info`, `drm_pvr_dev_query_hwrt_info`가 담당합니다. Hardware variation은 `drm_pvr_dev_query_quirks`와 `drm_pvr_dev_query_enhancements`로 표현합니다.

Heap query는 `drm_pvr_heap_id`, `drm_pvr_heap`, `drm_pvr_dev_query_heap_info`를 사용하고, firmware·hardware가 요구하는 static data area는 usage·area·query result identifier로 문서화합니다.

======
.. kernel-doc:: include/uapi/drm/pvr_drm.h
   :doc: PowerVR IOCTL interface

.. kernel-doc:: include/uapi/drm/pvr_drm.h
   :identifiers: PVR_IOCTL

DEV_QUERY
---------
.. kernel-doc:: include/uapi/drm/pvr_drm.h
   :doc: PowerVR IOCTL DEV_QUERY interface

.. kernel-doc:: include/uapi/drm/pvr_drm.h
   :identifiers: drm_pvr_dev_query

.. kernel-doc:: include/uapi/drm/pvr_drm.h
   :identifiers: drm_pvr_ioctl_dev_query_args

.. kernel-doc:: include/uapi/drm/pvr_drm.h
   :identifiers: drm_pvr_dev_query_gpu_info
                 drm_pvr_dev_query_runtime_info
                 drm_pvr_dev_query_hwrt_info
                 drm_pvr_dev_query_quirks
                 drm_pvr_dev_query_enhancements

.. kernel-doc:: include/uapi/drm/pvr_drm.h
   :identifiers: drm_pvr_heap_id
                 drm_pvr_heap
                 drm_pvr_dev_query_heap_info

.. kernel-doc:: include/uapi/drm/pvr_drm.h
   :identifiers: drm_pvr_static_data_area_usage
                 drm_pvr_static_data_area
                 drm_pvr_dev_query_static_data_areas

CREATE_BO

Buffer object와 VM address-space

`CREATE_BO`는 PowerVR buffer object 생성 interface입니다. `drm_pvr_ioctl_create_bo_args` argument와 CREATE_BO flag 문서를 함께 제공합니다.

`GET_BO_MMAP_OFFSET`은 BO를 userspace에 mmap할 때 필요한 offset을 조회하며 `drm_pvr_ioctl_get_bo_mmap_offset_args`로 argument를 전달합니다.

`CREATE_VM_CONTEXT`와 `DESTROY_VM_CONTEXT`는 GPU virtual-memory context lifetime을 관리하며 각각의 argument structure를 문서화합니다.

`VM_MAP`과 `VM_UNMAP`은 BO 또는 memory range를 VM address space에 연결하거나 제거하는 interface이고 `drm_pvr_ioctl_vm_map_args`, `drm_pvr_ioctl_vm_unmap_args`를 사용합니다.

---------
.. kernel-doc:: include/uapi/drm/pvr_drm.h
   :doc: PowerVR IOCTL CREATE_BO interface

.. kernel-doc:: include/uapi/drm/pvr_drm.h
   :identifiers: drm_pvr_ioctl_create_bo_args

.. kernel-doc:: include/uapi/drm/pvr_drm.h
   :doc: Flags for CREATE_BO

GET_BO_MMAP_OFFSET
------------------
.. kernel-doc:: include/uapi/drm/pvr_drm.h
   :doc: PowerVR IOCTL GET_BO_MMAP_OFFSET interface

.. kernel-doc:: include/uapi/drm/pvr_drm.h
   :identifiers: drm_pvr_ioctl_get_bo_mmap_offset_args

CREATE_VM_CONTEXT and DESTROY_VM_CONTEXT
----------------------------------------
.. kernel-doc:: include/uapi/drm/pvr_drm.h
   :doc: PowerVR IOCTL CREATE_VM_CONTEXT and DESTROY_VM_CONTEXT interfaces

.. kernel-doc:: include/uapi/drm/pvr_drm.h
   :identifiers: drm_pvr_ioctl_create_vm_context_args
                 drm_pvr_ioctl_destroy_vm_context_args

VM_MAP and VM_UNMAP
-------------------
.. kernel-doc:: include/uapi/drm/pvr_drm.h
   :doc: PowerVR IOCTL VM_MAP and VM_UNMAP interfaces

.. kernel-doc:: include/uapi/drm/pvr_drm.h
   :identifiers: drm_pvr_ioctl_vm_map_args
                 drm_pvr_ioctl_vm_unmap_args

Execution context와 free list

`CREATE_CONTEXT`와 `DESTROY_CONTEXT`는 PowerVR execution context lifetime을 관리합니다. Create argument 외에 context priority·type, static render context state와 format, reset framework와 format identifier를 연결합니다.

Destroy path는 `drm_pvr_ioctl_destroy_context_args`를 별도로 문서화합니다.

`CREATE_FREE_LIST`와 `DESTROY_FREE_LIST`는 hardware rendering에서 사용할 free-list resource lifetime을 관리하고 create·destroy argument structure를 각각 제공합니다.

CREATE_CONTEXT and DESTROY_CONTEXT
----------------------------------
.. kernel-doc:: include/uapi/drm/pvr_drm.h
   :doc: PowerVR IOCTL CREATE_CONTEXT and DESTROY_CONTEXT interfaces

.. kernel-doc:: include/uapi/drm/pvr_drm.h
   :identifiers: drm_pvr_ioctl_create_context_args

.. kernel-doc:: include/uapi/drm/pvr_drm.h
   :identifiers: drm_pvr_ctx_priority
                 drm_pvr_ctx_type
                 drm_pvr_static_render_context_state
                 drm_pvr_static_render_context_state_format
                 drm_pvr_reset_framework
                 drm_pvr_reset_framework_format

.. kernel-doc:: include/uapi/drm/pvr_drm.h
   :identifiers: drm_pvr_ioctl_destroy_context_args

CREATE_FREE_LIST and DESTROY_FREE_LIST
--------------------------------------
.. kernel-doc:: include/uapi/drm/pvr_drm.h
   :doc: PowerVR IOCTL CREATE_FREE_LIST and DESTROY_FREE_LIST interfaces

.. kernel-doc:: include/uapi/drm/pvr_drm.h
   :identifiers: drm_pvr_ioctl_create_free_list_args

.. kernel-doc:: include/uapi/drm/pvr_drm.h
   :identifiers: drm_pvr_ioctl_destroy_free_list_args

HWRT dataset lifetime

`CREATE_HWRT_DATASET`과 `DESTROY_HWRT_DATASET`은 hardware render-target dataset lifetime을 관리합니다.

Create argument는 `drm_pvr_ioctl_create_hwrt_dataset_args`, geometry·render-target data는 `drm_pvr_create_hwrt_geom_data_args`와 `drm_pvr_create_hwrt_rt_data_args`, destroy argument는 `drm_pvr_ioctl_destroy_hwrt_dataset_args`로 문서화합니다.

CREATE_HWRT_DATASET and DESTROY_HWRT_DATASET
--------------------------------------------
.. kernel-doc:: include/uapi/drm/pvr_drm.h
   :doc: PowerVR IOCTL CREATE_HWRT_DATASET and DESTROY_HWRT_DATASET interfaces

.. kernel-doc:: include/uapi/drm/pvr_drm.h
   :identifiers: drm_pvr_ioctl_create_hwrt_dataset_args

.. kernel-doc:: include/uapi/drm/pvr_drm.h
   :identifiers: drm_pvr_create_hwrt_geom_data_args
                 drm_pvr_create_hwrt_rt_data_args

.. kernel-doc:: include/uapi/drm/pvr_drm.h
   :identifiers: drm_pvr_ioctl_destroy_hwrt_dataset_args

SUBMIT_JOBS

Job submission과 synchronization

`SUBMIT_JOBS`는 PowerVR job submission interface입니다. `drm_pvr_ioctl_submit_jobs_args`가 IOCTL argument를 정의합니다.

Synchronization은 `drm_pvr_sync_op` object와 그 flag로 표현합니다. Job type은 `drm_pvr_job_type`, hardware render-target reference는 `drm_pvr_hwrt_data_ref`, 개별 job은 `drm_pvr_job`이 나타냅니다.

Command 종류별 flag는 geometry, fragment, compute, transfer command 각각에 대해 별도 kernel-doc block으로 정의됩니다.

-----------
.. kernel-doc:: include/uapi/drm/pvr_drm.h
   :doc: PowerVR IOCTL SUBMIT_JOBS interface

.. kernel-doc:: include/uapi/drm/pvr_drm.h
   :doc: Flags for the drm_pvr_sync_op object.

.. kernel-doc:: include/uapi/drm/pvr_drm.h
   :identifiers: drm_pvr_ioctl_submit_jobs_args

.. kernel-doc:: include/uapi/drm/pvr_drm.h
   :doc: Flags for SUBMIT_JOB ioctl geometry command.

.. kernel-doc:: include/uapi/drm/pvr_drm.h
   :doc: Flags for SUBMIT_JOB ioctl fragment command.

.. kernel-doc:: include/uapi/drm/pvr_drm.h
   :doc: Flags for SUBMIT_JOB ioctl compute command.

.. kernel-doc:: include/uapi/drm/pvr_drm.h
   :doc: Flags for SUBMIT_JOB ioctl transfer command.

.. kernel-doc:: include/uapi/drm/pvr_drm.h
   :identifiers: drm_pvr_sync_op
                 drm_pvr_job_type
                 drm_pvr_hwrt_data_ref
                 drm_pvr_job

Internal notes

IOCTL ABI validation helper

Internal note는 `drivers/gpu/drm/imagination/pvr_device.h`의 IOCTL validation helper를 연결합니다.

`PVR_STATIC_ASSERT_64BIT_ALIGNED`, `PVR_IOCTL_UNION_PADDING_CHECK`, `pvr_ioctl_union_padding_check`는 UAPI structure의 64-bit alignment와 union padding을 compile-time 또는 validation path에서 확인하는 identifier입니다.

==============
.. kernel-doc:: drivers/gpu/drm/imagination/pvr_device.h
   :doc: IOCTL validation helpers

.. kernel-doc:: drivers/gpu/drm/imagination/pvr_device.h
   :identifiers: PVR_STATIC_ASSERT_64BIT_ALIGNED PVR_IOCTL_UNION_PADDING_CHECK
                 pvr_ioctl_union_padding_check