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