path: root/include/uapi/drm/pvr_drm.h

/* SPDX-License-Identifier: (GPL-2.0-only WITH Linux-syscall-note) OR MIT */
/* Copyright (c) 2023 Imagination Technologies Ltd. */

#ifndef PVR_DRM_UAPI_H
#define PVR_DRM_UAPI_H

#include "drm.h"

#include <linux/const.h>
#include <linux/types.h>

#if defined(__cplusplus)
extern "C" {
#endif

/**
 * DOC: PowerVR UAPI
 *
 * The PowerVR IOCTL argument structs have a few limitations in place, in
 * addition to the standard kernel restrictions:
 *
 *  - All members must be type-aligned.
 *  - The overall struct must be padded to 64-bit alignment.
 *  - Explicit padding is almost always required. This takes the form of
 *    ``_padding_[x]`` members of sufficient size to pad to the next power-of-two
 *    alignment, where [x] is the offset into the struct in hexadecimal. Arrays
 *    are never used for alignment. Padding fields must be zeroed; this is
 *    always checked.
 *  - Unions may only appear as the last member of a struct.
 *  - Individual union members may grow in the future. The space between the
 *    end of a union member and the end of its containing union is considered
 *    "implicit padding" and must be zeroed. This is always checked.
 *
 * In addition to the IOCTL argument structs, the PowerVR UAPI makes use of
 * DEV_QUERY argument structs. These are used to fetch information about the
 * device and runtime. These structs are subject to the same rules set out
 * above.
 */

/**
 * struct drm_pvr_obj_array - Container used to pass arrays of objects
 *
 * It is not unusual to have to extend objects to pass new parameters, and the DRM
 * ioctl infrastructure is supporting that by padding ioctl arguments with zeros
 * when the data passed by userspace is smaller than the struct defined in the
 * drm_ioctl_desc, thus keeping things backward compatible. This type is just
 * applying the same concepts to indirect objects passed through arrays referenced
 * from the main ioctl arguments structure: the stride basically defines the size
 * of the object passed by userspace, which allows the kernel driver to pad with
 * zeros when it's smaller than the size of the object it expects.
 *
 * Use ``DRM_PVR_OBJ_ARRAY()`` to fill object array fields, unless you
 * have a very good reason not to.
 */
struct drm_pvr_obj_array {
	/** @stride: Stride of object struct. Used for versioning. */
	__u32 stride;

	/** @count: Number of objects in the array. */
	__u32 count;

	/** @array: User pointer to an array of objects. */
	__u64 array;
};

/**
 * DRM_PVR_OBJ_ARRAY() - Helper macro for filling &struct drm_pvr_obj_array.
 * @cnt: Number of elements pointed to py @ptr.
 * @ptr: Pointer to start of a C array.
 *
 * Return: Literal of type &struct drm_pvr_obj_array.
 */
#define DRM_PVR_OBJ_ARRAY(cnt, ptr) \
	{ .stride = sizeof((ptr)[0]), .count = (cnt), .array = (__u64)(uintptr_t)(ptr) }

/**
 * DOC: PowerVR IOCTL interface
 */

/**
 * PVR_IOCTL() - Build a PowerVR IOCTL number
 * @_ioctl: An incrementing id for this IOCTL. Added to %DRM_COMMAND_BASE.
 * @_mode: Must be one of %DRM_IOR, %DRM_IOW or %DRM_IOWR.
 * @_data: The type of the args struct passed by this IOCTL.
 *
 * The struct referred to by @_data must have a ``drm_pvr_ioctl_`` prefix and an
 * ``_args suffix``. They are therefore omitted from @_data.
 *
 * This should only be used to build the constants described below; it should
 * never be used to call an IOCTL directly.
 *
 * Return: An IOCTL number to be passed to ioctl() from userspace.
 */
#define PVR_IOCTL(_ioctl, _mode, _data) \
	_mode(DRM_COMMAND_BASE + (_ioctl), struct drm_pvr_ioctl_##_data##_args)

#define DRM_IOCTL_PVR_DEV_QUERY PVR_IOCTL(0x00, DRM_IOWR, dev_query)
#define DRM_IOCTL_PVR_CREATE_BO PVR_IOCTL(0x01, DRM_IOWR, create_bo)
#define DRM_IOCTL_PVR_GET_BO_MMAP_OFFSET PVR_IOCTL(0x02, DRM_IOWR, get_bo_mmap_offset)
#define DRM_IOCTL_PVR_CREATE_VM_CONTEXT PVR_IOCTL(0x03, DRM_IOWR, create_vm_context)
#define DRM_IOCTL_PVR_DESTROY_VM_CONTEXT PVR_IOCTL(0x04, DRM_IOW, destroy_vm_context)
#define DRM_IOCTL_PVR_VM_MAP PVR_IOCTL(0x05, DRM_IOW, vm_map)
#define DRM_IOCTL_PVR_VM_UNMAP PVR_IOCTL(0x06, DRM_IOW, vm_unmap)
#define DRM_IOCTL_PVR_CREATE_CONTEXT PVR_IOCTL(0x07, DRM_IOWR, create_context)
#define DRM_IOCTL_PVR_DESTROY_CONTEXT PVR_IOCTL(0x08, DRM_IOW, destroy_context)
#define DRM_IOCTL_PVR_CREATE_FREE_LIST PVR_IOCTL(0x09, DRM_IOWR, create_free_list)
#define DRM_IOCTL_PVR_DESTROY_FREE_LIST PVR_IOCTL(0x0a, DRM_IOW, destroy_free_list)
#define DRM_IOCTL_PVR_CREATE_HWRT_DATASET PVR_IOCTL(0x0b, DRM_IOWR, create_hwrt_dataset)
#define DRM_IOCTL_PVR_DESTROY_HWRT_DATASET PVR_IOCTL(0x0c, DRM_IOW, destroy_hwrt_dataset)
#define DRM_IOCTL_PVR_SUBMIT_JOBS PVR_IOCTL(0x0d, DRM_IOW, submit_jobs)

/**
 * DOC: PowerVR IOCTL DEV_QUERY interface
 */

/**
 * struct drm_pvr_dev_query_gpu_info - Container used to fetch information about
 * the graphics processor.
 *
 * When fetching this type &struct drm_pvr_ioctl_dev_query_args.type must be set
 * to %DRM_PVR_DEV_QUERY_GPU_INFO_GET.
 */
struct drm_pvr_dev_query_gpu_info {
	/**
	 * @gpu_id: GPU identifier.
	 *
	 * For all currently supported GPUs this is the BVNC encoded as a 64-bit
	 * value as follows:
	 *
	 *    +--------+--------+--------+-------+
	 *    | 63..48 | 47..32 | 31..16 | 15..0 |
	 *    +========+========+========+=======+
	 *    | B      | V      | N      | C     |
	 *    +--------+--------+--------+-------+
	 */
	__u64 gpu_id;

	/**
	 * @num_phantoms: Number of Phantoms present.
	 */
	__u32 num_phantoms;

	/** @_padding_c: Reserved. This field must be zeroed. */
	__u32 _padding_c;
};

/**
 * struct drm_pvr_dev_query_runtime_info - Container used to fetch information
 * about the graphics runtime.
 *
 * When fetching this type &struct drm_pvr_ioctl_dev_query_args.type must be set
 * to %DRM_PVR_DEV_QUERY_RUNTIME_INFO_GET.
 */
struct drm_pvr_dev_query_runtime_info {
	/**
	 * @free_list_min_pages: Minimum allowed free list size,
	 * in PM physical pages.
	 */
	__u64 free_list_min_pages;

	/**
	 * @free_list_max_pages: Maximum allowed free list size,
	 * in PM physical pages.
	 */
	__u64 free_list_max_pages;

	/**
	 * @common_store_alloc_region_size: Size of the Allocation
	 * Region within the Common Store used for coefficient and shared
	 * registers, in dwords.
	 */
	__u32 common_store_alloc_region_size;

	/**
	 * @common_store_partition_space_size: Size of the
	 * Partition Space within the Common Store for output buffers, in
	 * dwords.
	 */
	__u32 common_store_partition_space_size;

	/**
	 * @max_coeffs: Maximum coefficients, in dwords.
	 */
	__u32 max_coeffs;

	/**
	 * @cdm_max_local_mem_size_regs: Maximum amount of local
	 * memory available to a compute kernel, in dwords.
	 */
	__u32 cdm_max_local_mem_size_regs;
};

/**
 * struct drm_pvr_dev_query_quirks - Container used to fetch information about
 * hardware fixes for which the device may require support in the user mode
 * driver.
 *
 * When fetching this type &struct drm_pvr_ioctl_dev_query_args.type must be set
 * to %DRM_PVR_DEV_QUERY_QUIRKS_GET.
 */
struct