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_api.h>
12 #include <drm/ttm/ttm_bo_driver.h>
13 
14 #include <linux/dma-buf-map.h>
15 #include <linux/kernel.h> /* for container_of() */
16 
17 struct drm_mode_create_dumb;
18 struct drm_plane;
19 struct drm_plane_state;
20 struct drm_simple_display_pipe;
21 struct filp;
22 struct vm_area_struct;
23 
24 #define DRM_GEM_VRAM_PL_FLAG_SYSTEM	(1 << 0)
25 #define DRM_GEM_VRAM_PL_FLAG_VRAM	(1 << 1)
26 #define DRM_GEM_VRAM_PL_FLAG_TOPDOWN	(1 << 2)
27 
28 /*
29  * Buffer-object helpers
30  */
31 
32 /**
33  * struct drm_gem_vram_object - GEM object backed by VRAM
34  * @bo:		TTM buffer object
35  * @map:	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  *
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.
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
49  * drm_gem_vram_kmap() and drm_gem_vram_kunmap(), as well as pairs of
50  * drm_gem_vram_vmap() and drm_gem_vram_vunmap().
51  */
52 struct drm_gem_vram_object {
53 	struct ttm_buffer_object bo;
54 	struct dma_buf_map map;
55 
56 	/**
57 	 * @vmap_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 vmap_use_count;
63 
64 	/* Supported placements are %TTM_PL_VRAM and %TTM_PL_SYSTEM */
65 	struct ttm_placement placement;
66 	struct ttm_place placements[2];
67 };
68 
69 /**
70  * drm_gem_vram_of_bo - Returns the container of type
71  * &struct drm_gem_vram_object for field bo.
72  * @bo:		the VRAM buffer object
73  * Returns:	The containing GEM VRAM object
74  */
75 static inline struct drm_gem_vram_object *drm_gem_vram_of_bo(
76 	struct ttm_buffer_object *bo)
77 {
78 	return container_of(bo, struct drm_gem_vram_object, bo);
79 }
80 
81 /**
82  * drm_gem_vram_of_gem - Returns the container of type
83  * &struct drm_gem_vram_object for field gem.
84  * @gem:	the GEM object
85  * Returns:	The containing GEM VRAM object
86  */
87 static inline struct drm_gem_vram_object *drm_gem_vram_of_gem(
88 	struct drm_gem_object *gem)
89 {
90 	return container_of(gem, struct drm_gem_vram_object, bo.base);
91 }
92 
93 struct drm_gem_vram_object *drm_gem_vram_create(struct drm_device *dev,
94 						size_t size,
95 						unsigned long pg_align);
96 void drm_gem_vram_put(struct drm_gem_vram_object *gbo);
97 s64 drm_gem_vram_offset(struct drm_gem_vram_object *gbo);
98 int drm_gem_vram_pin(struct drm_gem_vram_object *gbo, unsigned long pl_flag);
99 int drm_gem_vram_unpin(struct drm_gem_vram_object *gbo);
100 int drm_gem_vram_vmap(struct drm_gem_vram_object *gbo, struct dma_buf_map *map);
101 void drm_gem_vram_vunmap(struct drm_gem_vram_object *gbo, struct dma_buf_map *map);
102 
103 int 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 
113 int 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  */
120 int
121 drm_gem_vram_plane_helper_prepare_fb(struct drm_plane *plane,
122 				     struct drm_plane_state *new_state);
123 void
124 drm_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 -
129  *	Initializes struct drm_plane_helper_funcs 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  * Helpers for struct drm_simple_display_pipe_funcs
141  */
142 
143 int drm_gem_vram_simple_display_pipe_prepare_fb(
144 	struct drm_simple_display_pipe *pipe,
145 	struct drm_plane_state *new_state);
146 
147 void drm_gem_vram_simple_display_pipe_cleanup_fb(
148 	struct drm_simple_display_pipe *pipe,
149 	struct drm_plane_state *old_state);
150 
151 /**
152  * define DRM_GEM_VRAM_DRIVER - default callback functions for \
153 	&struct drm_driver
154  *
155  * Drivers that use VRAM MM and GEM VRAM can use this macro to initialize
156  * &struct drm_driver with default functions.
157  */
158 #define DRM_GEM_VRAM_DRIVER \
159 	.debugfs_init             = drm_vram_mm_debugfs_init, \
160 	.dumb_create		  = drm_gem_vram_driver_dumb_create, \
161 	.dumb_map_offset	  = drm_gem_ttm_dumb_map_offset, \
162 	.gem_prime_mmap		  = drm_gem_prime_mmap
163 
164 /*
165  *  VRAM memory manager
166  */
167 
168 /**
169  * struct drm_vram_mm - An instance of VRAM MM
170  * @vram_base:	Base address of the managed video memory
171  * @vram_size:	Size of the managed video memory in bytes
172  * @bdev:	The TTM BO device.
173  * @funcs:	TTM BO functions
174  *
175  * The fields &struct drm_vram_mm.vram_base and
176  * &struct drm_vram_mm.vrm_size are managed by VRAM MM, but are
177  * available for public read access. Use the field
178  * &struct drm_vram_mm.bdev to access the TTM BO device.
179  */
180 struct drm_vram_mm {
181 	uint64_t vram_base;
182 	size_t vram_size;
183 
184 	struct ttm_device bdev;
185 };
186 
187 /**
188  * drm_vram_mm_of_bdev() - \
189 	Returns the container of type &struct ttm_device for field bdev.
190  * @bdev:	the TTM BO device
191  *
192  * Returns:
193  * The containing instance of &struct drm_vram_mm
194  */
195 static inline struct drm_vram_mm *drm_vram_mm_of_bdev(
196 	struct ttm_device *bdev)
197 {
198 	return container_of(bdev, struct drm_vram_mm, bdev);
199 }
200 
201 void drm_vram_mm_debugfs_init(struct drm_minor *minor);
202 
203 /*
204  * Helpers for integration with struct drm_device
205  */
206 
207 int drmm_vram_helper_init(struct drm_device *dev, uint64_t vram_base,
208 			  size_t vram_size);
209 
210 /*
211  * Mode-config helpers
212  */
213 
214 enum drm_mode_status
215 drm_vram_helper_mode_valid(struct drm_device *dev,
216 			   const struct drm_display_mode *mode);
217 
218 #endif
219