include/drm/drm_gem_vram_helper.h

0001 /* SPDX-License-Identifier: GPL-2.0-or-later */
0002
0003 #ifndef DRM_GEM_VRAM_HELPER_H
0004 #define DRM_GEM_VRAM_HELPER_H
0005
0006 #include <drm/drm_file.h>
0007 #include <drm/drm_gem.h>
0008 #include <drm/drm_gem_ttm_helper.h>
0009 #include <drm/drm_ioctl.h>
0010 #include <drm/drm_modes.h>
0011 #include <drm/ttm/ttm_bo_api.h>
0012 #include <drm/ttm/ttm_bo_driver.h>
0013
0014 #include <linux/container_of.h>
0015 #include <linux/iosys-map.h>
0016
0017 struct drm_mode_create_dumb;
0018 struct drm_plane;
0019 struct drm_plane_state;
0020 struct drm_simple_display_pipe;
0021 struct filp;
0022 struct vm_area_struct;
0023
0024 #define DRM_GEM_VRAM_PL_FLAG_SYSTEM (1 << 0)
0025 #define DRM_GEM_VRAM_PL_FLAG_VRAM   (1 << 1)
0026 #define DRM_GEM_VRAM_PL_FLAG_TOPDOWN    (1 << 2)
0027
0028 /*
0029  * Buffer-object helpers
0030  */
0031
0032 /**
0033  * struct drm_gem_vram_object - GEM object backed by VRAM
0034  * @bo:     TTM buffer object
0035  * @map:    Mapping information for @bo
0036  * @placement:  TTM placement information. Supported placements are \
0037     %TTM_PL_VRAM and %TTM_PL_SYSTEM
0038  * @placements: TTM placement information.
0039  *
0040  * The type struct drm_gem_vram_object represents a GEM object that is
0041  * backed by VRAM. It can be used for simple framebuffer devices with
0042  * dedicated memory. The buffer object can be evicted to system memory if
0043  * video memory becomes scarce.
0044  *
0045  * GEM VRAM objects perform reference counting for pin and mapping
0046  * operations. So a buffer object that has been pinned N times with
0047  * drm_gem_vram_pin() must be unpinned N times with
0048  * drm_gem_vram_unpin(). The same applies to pairs of
0049  * drm_gem_vram_kmap() and drm_gem_vram_kunmap(), as well as pairs of
0050  * drm_gem_vram_vmap() and drm_gem_vram_vunmap().
0051  */
0052 struct drm_gem_vram_object {
0053     struct ttm_buffer_object bo;
0054     struct iosys_map map;
0055
0056     /**
0057      * @vmap_use_count:
0058      *
0059      * Reference count on the virtual address.
0060      * The address are un-mapped when the count reaches zero.
0061      */
0062     unsigned int vmap_use_count;
0063
0064     /* Supported placements are %TTM_PL_VRAM and %TTM_PL_SYSTEM */
0065     struct ttm_placement placement;
0066     struct ttm_place placements[2];
0067 };
0068
0069 /**
0070  * drm_gem_vram_of_bo - Returns the container of type
0071  * &struct drm_gem_vram_object for field bo.
0072  * @bo:     the VRAM buffer object
0073  * Returns: The containing GEM VRAM object
0074  */
0075 static inline struct drm_gem_vram_object *drm_gem_vram_of_bo(
0076     struct ttm_buffer_object *bo)
0077 {
0078     return container_of(bo, struct drm_gem_vram_object, bo);
0079 }
0080
0081 /**
0082  * drm_gem_vram_of_gem - Returns the container of type
0083  * &struct drm_gem_vram_object for field gem.
0084  * @gem:    the GEM object
0085  * Returns: The containing GEM VRAM object
0086  */
0087 static inline struct drm_gem_vram_object *drm_gem_vram_of_gem(
0088     struct drm_gem_object *gem)
0089 {
0090     return container_of(gem, struct drm_gem_vram_object, bo.base);
0091 }
0092
0093 struct drm_gem_vram_object *drm_gem_vram_create(struct drm_device *dev,
0094                         size_t size,
0095                         unsigned long pg_align);
0096 void drm_gem_vram_put(struct drm_gem_vram_object *gbo);
0097 s64 drm_gem_vram_offset(struct drm_gem_vram_object *gbo);
0098 int drm_gem_vram_pin(struct drm_gem_vram_object *gbo, unsigned long pl_flag);
0099 int drm_gem_vram_unpin(struct drm_gem_vram_object *gbo);
0100 int drm_gem_vram_vmap(struct drm_gem_vram_object *gbo, struct iosys_map *map);
0101 void drm_gem_vram_vunmap(struct drm_gem_vram_object *gbo,
0102              struct iosys_map *map);
0103
0104 int drm_gem_vram_fill_create_dumb(struct drm_file *file,
0105                   struct drm_device *dev,
0106                   unsigned long pg_align,
0107                   unsigned long pitch_align,
0108                   struct drm_mode_create_dumb *args);
0109
0110 /*
0111  * Helpers for struct drm_driver
0112  */
0113
0114 int drm_gem_vram_driver_dumb_create(struct drm_file *file,
0115                     struct drm_device *dev,
0116                     struct drm_mode_create_dumb *args);
0117
0118 /*
0119  * Helpers for struct drm_plane_helper_funcs
0120  */
0121 int
0122 drm_gem_vram_plane_helper_prepare_fb(struct drm_plane *plane,
0123                      struct drm_plane_state *new_state);
0124 void
0125 drm_gem_vram_plane_helper_cleanup_fb(struct drm_plane *plane,
0126                      struct drm_plane_state *old_state);
0127
0128 /**
0129  * DRM_GEM_VRAM_PLANE_HELPER_FUNCS -
0130  *  Initializes struct drm_plane_helper_funcs for VRAM handling
0131  *
0132  * Drivers may use GEM BOs as VRAM helpers for the framebuffer memory. This
0133  * macro initializes struct drm_plane_helper_funcs to use the respective helper
0134  * functions.
0135  */
0136 #define DRM_GEM_VRAM_PLANE_HELPER_FUNCS \
0137     .prepare_fb = drm_gem_vram_plane_helper_prepare_fb, \
0138     .cleanup_fb = drm_gem_vram_plane_helper_cleanup_fb
0139
0140 /*
0141  * Helpers for struct drm_simple_display_pipe_funcs
0142  */
0143
0144 int drm_gem_vram_simple_display_pipe_prepare_fb(
0145     struct drm_simple_display_pipe *pipe,
0146     struct drm_plane_state *new_state);
0147
0148 void drm_gem_vram_simple_display_pipe_cleanup_fb(
0149     struct drm_simple_display_pipe *pipe,
0150     struct drm_plane_state *old_state);
0151
0152 /**
0153  * define DRM_GEM_VRAM_DRIVER - default callback functions for \
0154     &struct drm_driver
0155  *
0156  * Drivers that use VRAM MM and GEM VRAM can use this macro to initialize
0157  * &struct drm_driver with default functions.
0158  */
0159 #define DRM_GEM_VRAM_DRIVER \
0160     .debugfs_init             = drm_vram_mm_debugfs_init, \
0161     .dumb_create          = drm_gem_vram_driver_dumb_create, \
0162     .dumb_map_offset      = drm_gem_ttm_dumb_map_offset, \
0163     .gem_prime_mmap       = drm_gem_prime_mmap
0164
0165 /*
0166  *  VRAM memory manager
0167  */
0168
0169 /**
0170  * struct drm_vram_mm - An instance of VRAM MM
0171  * @vram_base:  Base address of the managed video memory
0172  * @vram_size:  Size of the managed video memory in bytes
0173  * @bdev:   The TTM BO device.
0174  * @funcs:  TTM BO functions
0175  *
0176  * The fields &struct drm_vram_mm.vram_base and
0177  * &struct drm_vram_mm.vrm_size are managed by VRAM MM, but are
0178  * available for public read access. Use the field
0179  * &struct drm_vram_mm.bdev to access the TTM BO device.
0180  */
0181 struct drm_vram_mm {
0182     uint64_t vram_base;
0183     size_t vram_size;
0184
0185     struct ttm_device bdev;
0186 };
0187
0188 /**
0189  * drm_vram_mm_of_bdev() - \
0190     Returns the container of type &struct ttm_device for field bdev.
0191  * @bdev:   the TTM BO device
0192  *
0193  * Returns:
0194  * The containing instance of &struct drm_vram_mm
0195  */
0196 static inline struct drm_vram_mm *drm_vram_mm_of_bdev(
0197     struct ttm_device *bdev)
0198 {
0199     return container_of(bdev, struct drm_vram_mm, bdev);
0200 }
0201
0202 void drm_vram_mm_debugfs_init(struct drm_minor *minor);
0203
0204 /*
0205  * Helpers for integration with struct drm_device
0206  */
0207
0208 int drmm_vram_helper_init(struct drm_device *dev, uint64_t vram_base,
0209               size_t vram_size);
0210
0211 /*
0212  * Mode-config helpers
0213  */
0214
0215 enum drm_mode_status
0216 drm_vram_helper_mode_valid(struct drm_device *dev,
0217                const struct drm_display_mode *mode);
0218
0219 #endif