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