drm_gem_vram_helper.h

  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_vmap(struct drm_gem_vram_object *gbo, struct iosys_map *map);
 98void drm_gem_vram_vunmap(struct drm_gem_vram_object *gbo,
 99			 struct iosys_map *map);
100
101int drm_gem_vram_fill_create_dumb(struct drm_file *file,
102				  struct drm_device *dev,
103				  unsigned long pg_align,
104				  unsigned long pitch_align,
105				  struct drm_mode_create_dumb *args);
106
107/*
108 * Helpers for struct drm_driver
109 */
110
111int drm_gem_vram_driver_dumb_create(struct drm_file *file,
112				    struct drm_device *dev,
113				    struct drm_mode_create_dumb *args);
114
115/*
116 * Helpers for struct drm_plane_helper_funcs
117 */
118int
119drm_gem_vram_plane_helper_prepare_fb(struct drm_plane *plane,
120				     struct drm_plane_state *new_state);
121void
122drm_gem_vram_plane_helper_cleanup_fb(struct drm_plane *plane,
123				     struct drm_plane_state *old_state);
124
125/**
126 * DRM_GEM_VRAM_PLANE_HELPER_FUNCS - Initializes struct drm_plane_helper_funcs
127 *				     for VRAM handling
128 *
129 * Drivers may use GEM BOs as VRAM helpers for the framebuffer memory. This
130 * macro initializes struct drm_plane_helper_funcs to use the respective helper
131 * functions.
132 */
133#define DRM_GEM_VRAM_PLANE_HELPER_FUNCS \
134	.prepare_fb = drm_gem_vram_plane_helper_prepare_fb, \
135	.cleanup_fb = drm_gem_vram_plane_helper_cleanup_fb
136
137/**
138 * define DRM_GEM_VRAM_DRIVER - default callback functions for
139 *				&struct drm_driver
140 *
141 * Drivers that use VRAM MM and GEM VRAM can use this macro to initialize
142 * &struct drm_driver with default functions.
143 */
144#define DRM_GEM_VRAM_DRIVER \
145	.debugfs_init	 = drm_vram_mm_debugfs_init, \
146	.dumb_create	 = drm_gem_vram_driver_dumb_create, \
147	.dumb_map_offset = drm_gem_ttm_dumb_map_offset
148
149/*
150 *  VRAM memory manager
151 */
152
153/**
154 * struct drm_vram_mm - An instance of VRAM MM
155 * @vram_base:	Base address of the managed video memory
156 * @vram_size:	Size of the managed video memory in bytes
157 * @bdev:	The TTM BO device.
158 *
159 * The fields &struct drm_vram_mm.vram_base and
160 * &struct drm_vram_mm.vrm_size are managed by VRAM MM, but are
161 * available for public read access. Use the field
162 * &struct drm_vram_mm.bdev to access the TTM BO device.
163 */
164struct drm_vram_mm {
165	uint64_t vram_base;
166	size_t vram_size;
167
168	struct ttm_device bdev;
169};
170
171/**
172 * drm_vram_mm_of_bdev() - Returns the container of type &struct ttm_device for
173 *			   field bdev.
174 * @bdev:	the TTM BO device
175 *
176 * Returns:
177 * The containing instance of &struct drm_vram_mm
178 */
179static inline struct drm_vram_mm *drm_vram_mm_of_bdev(
180	struct ttm_device *bdev)
181{
182	return container_of(bdev, struct drm_vram_mm, bdev);
183}
184
185void drm_vram_mm_debugfs_init(struct drm_minor *minor);
186
187/*
188 * Helpers for integration with struct drm_device
189 */
190
191int drmm_vram_helper_init(struct drm_device *dev, uint64_t vram_base,
192			  size_t vram_size);
193
194/*
195 * Mode-config helpers
196 */
197
198enum drm_mode_status
199drm_vram_helper_mode_valid(struct drm_device *dev,
200			   const struct drm_display_mode *mode);
201
202#endif