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