[linux-block.git] / include / drm / drm_gem_vram_helper.h

/* SPDX-License-Identifier: GPL-2.0-or-later */

#ifndef DRM_GEM_VRAM_HELPER_H
#define DRM_GEM_VRAM_HELPER_H

#include <drm/drm_file.h>
#include <drm/drm_gem.h>
#include <drm/drm_ioctl.h>
#include <drm/drm_modes.h>
#include <drm/ttm/ttm_bo_api.h>
#include <drm/ttm/ttm_bo_driver.h>

#include <linux/kernel.h> /* for container_of() */

struct drm_mode_create_dumb;
struct drm_plane;
struct drm_plane_state;
struct drm_simple_display_pipe;
struct filp;
struct vm_area_struct;

#define DRM_GEM_VRAM_PL_FLAG_SYSTEM	(1 << 0)
#define DRM_GEM_VRAM_PL_FLAG_VRAM	(1 << 1)
#define DRM_GEM_VRAM_PL_FLAG_TOPDOWN	(1 << 2)

/*
 * Buffer-object helpers
 */

/**
 * struct drm_gem_vram_object - GEM object backed by VRAM
 * @gem:	GEM object
 * @bo:		TTM buffer object
 * @kmap:	Mapping information for @bo
 * @placement:	TTM placement information. Supported placements are \
	%TTM_PL_VRAM and %TTM_PL_SYSTEM
 * @placements:	TTM placement information.
 * @pin_count:	Pin counter
 *
 * The type struct drm_gem_vram_object represents a GEM object that is
 * backed by VRAM. It can be used for simple framebuffer devices with
 * dedicated memory. The buffer object can be evicted to system memory if
 * video memory becomes scarce.
 *
 * GEM VRAM objects perform reference counting for pin and mapping
 * operations. So a buffer object that has been pinned N times with
 * drm_gem_vram_pin() must be unpinned N times with
 * drm_gem_vram_unpin(). The same applies to pairs of
 * drm_gem_vram_kmap() and drm_gem_vram_kunmap(), as well as pairs of
 * drm_gem_vram_vmap() and drm_gem_vram_vunmap().
 */
struct drm_gem_vram_object {
	struct ttm_buffer_object bo;
	struct ttm_bo_kmap_obj kmap;

	/**
	 * @kmap_use_count:
	 *
	 * Reference count on the virtual address.
	 * The address are un-mapped when the count reaches zero.
	 */
	unsigned int kmap_use_count;

	/* Supported placements are %TTM_PL_VRAM and %TTM_PL_SYSTEM */
	struct ttm_placement placement;
	struct ttm_place placements[2];

	int pin_count;
};

/**
 * Returns the container of type &struct drm_gem_vram_object
 * for field bo.
 * @bo:		the VRAM buffer object
 * Returns:	The containing GEM VRAM object
 */
static inline struct drm_gem_vram_object *drm_gem_vram_of_bo(
	struct ttm_buffer_object *bo)
{
	return container_of(bo, struct drm_gem_vram_object, bo);
}

/**
 * Returns the container of type &struct drm_gem_vram_object
 * for field gem.
 * @gem:	the GEM object
 * Returns:	The containing GEM VRAM object
 */
static inline struct drm_gem_vram_object *drm_gem_vram_of_gem(
	struct drm_gem_object *gem)
{
	return container_of(gem, struct drm_gem_vram_object, bo.base);
}

struct drm_gem_vram_object *drm_gem_vram_create(struct drm_device *dev,
						size_t size,
						unsigned long pg_align);
void drm_gem_vram_put(struct drm_gem_vram_object *gbo);
u64 drm_gem_vram_mmap_offset(struct drm_gem_vram_object *gbo);
s64 drm_gem_vram_offset(struct drm_gem_vram_object *gbo);
int drm_gem_vram_pin(struct drm_gem_vram_object *gbo, unsigned long pl_flag);
int drm_gem_vram_unpin(struct drm_gem_vram_object *gbo);
void *drm_gem_vram_kmap(struct drm_gem_vram_object *gbo, bool map,
			bool *is_iomem);
void drm_gem_vram_kunmap(struct drm_gem_vram_object *gbo);
void *drm_gem_vram_vmap(struct drm_gem_vram_object *gbo);
void drm_gem_vram_vunmap(struct drm_gem_vram_object *gbo, void *vaddr);

int drm_gem_vram_fill_create_dumb(struct drm_file *file,
				  struct drm_device *dev,
				  unsigned long pg_align,
				  unsigned long pitch_align,
				  struct drm_mode_create_dumb *args);

/*
 * Helpers for struct drm_driver
 */

int drm_gem_vram_driver_dumb_create(struct drm_file *file,
				    struct drm_device *dev,
				    struct drm_mode_create_dumb *args);
int drm_gem_vram_driver_dumb_mmap_offset(struct drm_file *file,
					 struct drm_device *dev,
					 uint32_t handle, uint64_t *offset);

/*
 * Helpers for struct drm_plane_helper_funcs
 */
int
drm_gem_vram_plane_helper_prepare_fb(struct drm_plane *plane,
				     struct drm_plane_state *new_state);
void
drm_gem_vram_plane_helper_cleanup_fb(struct drm_plane *plane,
				     struct drm_plane_state *old_state);

/*
 * Helpers for struct drm_simple_display_pipe_funcs
 */

int drm_gem_vram_simple_display_pipe_prepare_fb(
	struct drm_simple_display_pipe *pipe,
	struct drm_plane_state *new_state);

void drm_gem_vram_simple_display_pipe_cleanup_fb(
	struct drm_simple_display_pipe *pipe,
	struct drm_plane_state *old_state);

/**
 * define DRM_GEM_VRAM_DRIVER - default callback functions for \
	&struct drm_driver
 *
 * Drivers that use VRAM MM and GEM VRAM can use this macro to initialize
 * &struct drm_driver with default functions.
 */
#define DRM_GEM_VRAM_DRIVER \
	.debugfs_init             = drm_vram_mm_debugfs_init, \
	.dumb_create		  = drm_gem_vram_driver_dumb_create, \
	.dumb_map_offset	  = drm_gem_vram_driver_dumb_mmap_offset, \
	.gem_prime_mmap		  = drm_gem_prime_mmap

/*
 *  VRAM memory manager
 */

/**
 * struct drm_vram_mm - An instance of VRAM MM
 * @vram_base:	Base address of the managed video memory
 * @vram_size:	Size of the managed video memory in bytes
 * @bdev:	The TTM BO device.
 * @funcs:	TTM BO functions
 *
 * The fields &struct drm_vram_mm.vram_base and
 * &struct drm_vram_mm.vrm_size are managed by VRAM MM, but are
 * available for public read access. Use the field
 * &struct drm_vram_mm.bdev to access the TTM BO device.
 */
struct drm_vram_mm {
	uint64_t vram_base;
	size_t vram_size;

	struct ttm_bo_device bdev;
};

/**
 * drm_vram_mm_of_bdev() - \
	Returns the container of type &struct ttm_bo_device for field bdev.
 * @bdev:	the TTM BO device
 *
 * Returns:
 * The containing instance of &struct drm_vram_mm
 */
static inline struct drm_vram_mm *drm_vram_mm_of_bdev(
	struct ttm_bo_device *bdev)
{
	return container_of(bdev, struct drm_vram_mm, bdev);
}

void drm_vram_mm_debugfs_init(struct drm_minor *minor);

/*
 * Helpers for integration with struct drm_device
 */

struct drm_vram_mm *drm_vram_helper_alloc_mm(
	struct drm_device *dev, uint64_t vram_base, size_t vram_size);
void drm_vram_helper_release_mm(struct drm_device *dev);

int drmm_vram_helper_init(struct drm_device *dev, uint64_t vram_base,
			  size_t vram_size);

/*
 * Mode-config helpers
 */

enum drm_mode_status
drm_vram_helper_mode_valid(struct drm_device *dev,
			   const struct drm_display_mode *mode);

#endif
Commit	Line	Data
85438a8d TZ	1	/* SPDX-License-Identifier: GPL-2.0-or-later */
	2
	3	#ifndef DRM_GEM_VRAM_HELPER_H
	4	#define DRM_GEM_VRAM_HELPER_H
	5
6b5ce4a1	6	#include <drm/drm_file.h>
85438a8d	7	#include <drm/drm_gem.h>
6b5ce4a1	8	#include <drm/drm_ioctl.h>
80f7c3f7	9	#include <drm/drm_modes.h>
85438a8d	10	#include <drm/ttm/ttm_bo_api.h>
6b5ce4a1	11	#include <drm/ttm/ttm_bo_driver.h>
6b5ce4a1	12
85438a8d TZ	13	#include <linux/kernel.h> /* for container_of() */
85438a8d TZ	14
fed1eec0	15	struct drm_mode_create_dumb;
6542ad89 TZ	16	struct drm_plane;
	17	struct drm_plane_state;
	18	struct drm_simple_display_pipe;
85438a8d	19	struct filp;
59f5989a	20	struct vm_area_struct;
85438a8d	21
7053e0ea CK	22	#define DRM_GEM_VRAM_PL_FLAG_SYSTEM (1 << 0)
	23	#define DRM_GEM_VRAM_PL_FLAG_VRAM (1 << 1)
	24	#define DRM_GEM_VRAM_PL_FLAG_TOPDOWN (1 << 2)
85438a8d TZ	25
	26	/*
	27	* Buffer-object helpers
	28	*/
	29
	30	/**
	31	* struct drm_gem_vram_object - GEM object backed by VRAM
	32	* @gem: GEM object
	33	* @bo: TTM buffer object
	34	* @kmap: Mapping information for @bo
	35	* @placement: TTM placement information. Supported placements are \
	36	%TTM_PL_VRAM and %TTM_PL_SYSTEM
	37	* @placements: TTM placement information.
	38	* @pin_count: Pin counter
	39	*
	40	* The type struct drm_gem_vram_object represents a GEM object that is
	41	* backed by VRAM. It can be used for simple framebuffer devices with
	42	* dedicated memory. The buffer object can be evicted to system memory if
	43	* video memory becomes scarce.
37a48adf TZ	44	*
	45	* GEM VRAM objects perform reference counting for pin and mapping
	46	* operations. So a buffer object that has been pinned N times with
	47	* drm_gem_vram_pin() must be unpinned N times with
	48	* drm_gem_vram_unpin(). The same applies to pairs of
c8908bde TZ	49	* drm_gem_vram_kmap() and drm_gem_vram_kunmap(), as well as pairs of
c8908bde TZ	50	* drm_gem_vram_vmap() and drm_gem_vram_vunmap().
85438a8d TZ	51	*/
85438a8d TZ	52	struct drm_gem_vram_object {
85438a8d TZ	53	struct ttm_buffer_object bo;
	54	struct ttm_bo_kmap_obj kmap;
	55
37a48adf TZ	56	/**
	57	* @kmap_use_count:
	58	*
	59	* Reference count on the virtual address.
	60	* The address are un-mapped when the count reaches zero.
	61	*/
	62	unsigned int kmap_use_count;
	63
85438a8d TZ	64	/* Supported placements are %TTM_PL_VRAM and %TTM_PL_SYSTEM */
	65	struct ttm_placement placement;
	66	struct ttm_place placements[2];
	67
	68	int pin_count;
	69	};
	70
	71	/**
	72	* Returns the container of type &struct drm_gem_vram_object
	73	* for field bo.
	74	* @bo: the VRAM buffer object
	75	* Returns: The containing GEM VRAM object
	76	*/
	77	static inline struct drm_gem_vram_object *drm_gem_vram_of_bo(
	78	struct ttm_buffer_object *bo)
	79	{
	80	return container_of(bo, struct drm_gem_vram_object, bo);
	81	}
	82
	83	/**
	84	* Returns the container of type &struct drm_gem_vram_object
	85	* for field gem.
	86	* @gem: the GEM object
	87	* Returns: The containing GEM VRAM object
	88	*/
	89	static inline struct drm_gem_vram_object *drm_gem_vram_of_gem(
	90	struct drm_gem_object *gem)
	91	{
0e580c6d	92	return container_of(gem, struct drm_gem_vram_object, bo.base);
85438a8d TZ	93	}
	94
	95	struct drm_gem_vram_object drm_gem_vram_create(struct drm_device dev,
85438a8d	96	size_t size,
ebe9428b	97	unsigned long pg_align);
85438a8d	98	void drm_gem_vram_put(struct drm_gem_vram_object *gbo);
85438a8d TZ	99	u64 drm_gem_vram_mmap_offset(struct drm_gem_vram_object *gbo);
	100	s64 drm_gem_vram_offset(struct drm_gem_vram_object *gbo);
	101	int drm_gem_vram_pin(struct drm_gem_vram_object *gbo, unsigned long pl_flag);
	102	int drm_gem_vram_unpin(struct drm_gem_vram_object *gbo);
85438a8d TZ	103	void drm_gem_vram_kmap(struct drm_gem_vram_object gbo, bool map,
85438a8d TZ	104	bool *is_iomem);
85438a8d	105	void drm_gem_vram_kunmap(struct drm_gem_vram_object *gbo);
c8908bde TZ	106	void drm_gem_vram_vmap(struct drm_gem_vram_object gbo);
c8908bde TZ	107	void drm_gem_vram_vunmap(struct drm_gem_vram_object gbo, void vaddr);
85438a8d	108
fed1eec0 TZ	109	int drm_gem_vram_fill_create_dumb(struct drm_file *file,
fed1eec0 TZ	110	struct drm_device *dev,
fed1eec0	111	unsigned long pg_align,
98707327	112	unsigned long pitch_align,
fed1eec0 TZ	113	struct drm_mode_create_dumb *args);
fed1eec0 TZ	114
737000fd TZ	115	/*
	116	* Helpers for struct drm_driver
	117	*/
	118
59f5989a TZ	119	int drm_gem_vram_driver_dumb_create(struct drm_file *file,
	120	struct drm_device *dev,
	121	struct drm_mode_create_dumb *args);
737000fd TZ	122	int drm_gem_vram_driver_dumb_mmap_offset(struct drm_file *file,
	123	struct drm_device *dev,
	124	uint32_t handle, uint64_t *offset);
59f5989a	125
6542ad89 TZ	126	/*
	127	* Helpers for struct drm_plane_helper_funcs
	128	*/
	129	int
	130	drm_gem_vram_plane_helper_prepare_fb(struct drm_plane *plane,
	131	struct drm_plane_state *new_state);
	132	void
	133	drm_gem_vram_plane_helper_cleanup_fb(struct drm_plane *plane,
	134	struct drm_plane_state *old_state);
	135
	136	/*
	137	* Helpers for struct drm_simple_display_pipe_funcs
	138	*/
	139
	140	int drm_gem_vram_simple_display_pipe_prepare_fb(
	141	struct drm_simple_display_pipe *pipe,
	142	struct drm_plane_state *new_state);
	143
	144	void drm_gem_vram_simple_display_pipe_cleanup_fb(
	145	struct drm_simple_display_pipe *pipe,
	146	struct drm_plane_state *old_state);
	147
59f5989a TZ	148	/**
	149	* define DRM_GEM_VRAM_DRIVER - default callback functions for \
	150	&struct drm_driver
	151	*
	152	* Drivers that use VRAM MM and GEM VRAM can use this macro to initialize
	153	* &struct drm_driver with default functions.
	154	*/
	155	#define DRM_GEM_VRAM_DRIVER \
9286766b	156	.debugfs_init = drm_vram_mm_debugfs_init, \
59f5989a	157	.dumb_create = drm_gem_vram_driver_dumb_create, \
31070a87 TZ	158	.dumb_map_offset = drm_gem_vram_driver_dumb_mmap_offset, \
31070a87 TZ	159	.gem_prime_mmap = drm_gem_prime_mmap
59f5989a	160
6b5ce4a1 TZ	161	/*
	162	* VRAM memory manager
	163	*/
	164
	165	/**
	166	* struct drm_vram_mm - An instance of VRAM MM
	167	* @vram_base: Base address of the managed video memory
	168	* @vram_size: Size of the managed video memory in bytes
	169	* @bdev: The TTM BO device.
	170	* @funcs: TTM BO functions
	171	*
	172	* The fields &struct drm_vram_mm.vram_base and
	173	* &struct drm_vram_mm.vrm_size are managed by VRAM MM, but are
	174	* available for public read access. Use the field
	175	* &struct drm_vram_mm.bdev to access the TTM BO device.
	176	*/
	177	struct drm_vram_mm {
	178	uint64_t vram_base;
	179	size_t vram_size;
	180
	181	struct ttm_bo_device bdev;
6b5ce4a1 TZ	182	};
	183
	184	/**
	185	* drm_vram_mm_of_bdev() - \
	186	Returns the container of type &struct ttm_bo_device for field bdev.
	187	* @bdev: the TTM BO device
	188	*
	189	* Returns:
	190	* The containing instance of &struct drm_vram_mm
	191	*/
	192	static inline struct drm_vram_mm *drm_vram_mm_of_bdev(
	193	struct ttm_bo_device *bdev)
	194	{
	195	return container_of(bdev, struct drm_vram_mm, bdev);
	196	}
	197
7ce84471	198	void drm_vram_mm_debugfs_init(struct drm_minor *minor);
6b5ce4a1 TZ	199
	200	/*
	201	* Helpers for integration with struct drm_device
	202	*/
	203
	204	struct drm_vram_mm *drm_vram_helper_alloc_mm(
b0e40e08	205	struct drm_device *dev, uint64_t vram_base, size_t vram_size);
6b5ce4a1 TZ	206	void drm_vram_helper_release_mm(struct drm_device *dev);
6b5ce4a1 TZ	207
a5f23a72 TZ	208	int drmm_vram_helper_init(struct drm_device *dev, uint64_t vram_base,
	209	size_t vram_size);
	210
80f7c3f7 TZ	211	/*
	212	* Mode-config helpers
	213	*/
	214
	215	enum drm_mode_status
	216	drm_vram_helper_mode_valid(struct drm_device *dev,
	217	const struct drm_display_mode *mode);
	218
85438a8d	219	#endif