include/drm/drm_gem_atomic_helper.h

   1 /* SPDX-License-Identifier: GPL-2.0-or-later */
   2
   3 #ifndef __DRM_GEM_ATOMIC_HELPER_H__
   4 #define __DRM_GEM_ATOMIC_HELPER_H__
   5
   6 #include <linux/iosys-map.h>
   7
   8 #include <drm/drm_fourcc.h>
   9 #include <drm/drm_plane.h>
  10
  11 struct drm_simple_display_pipe;
  12
  13 /*
  14  * Plane Helpers
  15  */
  16
  17 int drm_gem_plane_helper_prepare_fb(struct drm_plane *plane, struct drm_plane_state *state);
  18 int drm_gem_simple_display_pipe_prepare_fb(struct drm_simple_display_pipe *pipe,
  19                                            struct drm_plane_state *plane_state);
  20
  21 /*
  22  * Helpers for planes with shadow buffers
  23  */
  24
  25 /**
  26  * DRM_SHADOW_PLANE_MAX_WIDTH - Maximum width of a plane's shadow buffer in pixels
  27  *
  28  * For drivers with shadow planes, the maximum width of the framebuffer is
  29  * usually independent from hardware limitations. Drivers can initialize struct
  30  * drm_mode_config.max_width from DRM_SHADOW_PLANE_MAX_WIDTH.
  31  */
  32 #define DRM_SHADOW_PLANE_MAX_WIDTH      (4096u)
  33
  34 /**
  35  * DRM_SHADOW_PLANE_MAX_HEIGHT - Maximum height of a plane's shadow buffer in scanlines
  36  *
  37  * For drivers with shadow planes, the maximum height of the framebuffer is
  38  * usually independent from hardware limitations. Drivers can initialize struct
  39  * drm_mode_config.max_height from DRM_SHADOW_PLANE_MAX_HEIGHT.
  40  */
  41 #define DRM_SHADOW_PLANE_MAX_HEIGHT     (4096u)
  42
  43 /**
  44  * struct drm_shadow_plane_state - plane state for planes with shadow buffers
  45  *
  46  * For planes that use a shadow buffer, struct drm_shadow_plane_state
  47  * provides the regular plane state plus mappings of the shadow buffer
  48  * into kernel address space.
  49  */
  50 struct drm_shadow_plane_state {
  51         /** @base: plane state */
  52         struct drm_plane_state base;
  53
  54         /* Transitional state - do not export or duplicate */
  55
  56         /**
  57          * @map: Mappings of the plane's framebuffer BOs in to kernel address space
  58          *
  59          * The memory mappings stored in map should be established in the plane's
  60          * prepare_fb callback and removed in the cleanup_fb callback.
  61          */
  62         struct iosys_map map[DRM_FORMAT_MAX_PLANES];
  63
  64         /**
  65          * @data: Address of each framebuffer BO's data
  66          *
  67          * The address of the data stored in each mapping. This is different
  68          * for framebuffers with non-zero offset fields.
  69          */
  70         struct iosys_map data[DRM_FORMAT_MAX_PLANES];
  71 };
  72
  73 /**
  74  * to_drm_shadow_plane_state - upcasts from struct drm_plane_state
  75  * @state: the plane state
  76  */
  77 static inline struct drm_shadow_plane_state *
  78 to_drm_shadow_plane_state(struct drm_plane_state *state)
  79 {
  80         return container_of(state, struct drm_shadow_plane_state, base);
  81 }
  82
  83 void __drm_gem_duplicate_shadow_plane_state(struct drm_plane *plane,
  84                                             struct drm_shadow_plane_state *new_shadow_plane_state);
  85 void __drm_gem_destroy_shadow_plane_state(struct drm_shadow_plane_state *shadow_plane_state);
  86 void __drm_gem_reset_shadow_plane(struct drm_plane *plane,
  87                                   struct drm_shadow_plane_state *shadow_plane_state);
  88
  89 void drm_gem_reset_shadow_plane(struct drm_plane *plane);
  90 struct drm_plane_state *drm_gem_duplicate_shadow_plane_state(struct drm_plane *plane);
  91 void drm_gem_destroy_shadow_plane_state(struct drm_plane *plane,
  92                                         struct drm_plane_state *plane_state);
  93
  94 /**
  95  * DRM_GEM_SHADOW_PLANE_FUNCS -
  96  *      Initializes struct drm_plane_funcs for shadow-buffered planes
  97  *
  98  * Drivers may use GEM BOs as shadow buffers over the framebuffer memory. This
  99  * macro initializes struct drm_plane_funcs to use the rsp helper functions.
 100  */
 101 #define DRM_GEM_SHADOW_PLANE_FUNCS \
 102         .reset = drm_gem_reset_shadow_plane, \
 103         .atomic_duplicate_state = drm_gem_duplicate_shadow_plane_state, \
 104         .atomic_destroy_state = drm_gem_destroy_shadow_plane_state
 105
 106 int drm_gem_prepare_shadow_fb(struct drm_plane *plane, struct drm_plane_state *plane_state);
 107 void drm_gem_cleanup_shadow_fb(struct drm_plane *plane, struct drm_plane_state *plane_state);
 108
 109 /**
 110  * DRM_GEM_SHADOW_PLANE_HELPER_FUNCS -
 111  *      Initializes struct drm_plane_helper_funcs for shadow-buffered planes
 112  *
 113  * Drivers may use GEM BOs as shadow buffers over the framebuffer memory. This
 114  * macro initializes struct drm_plane_helper_funcs to use the rsp helper
 115  * functions.
 116  */
 117 #define DRM_GEM_SHADOW_PLANE_HELPER_FUNCS \
 118         .prepare_fb = drm_gem_prepare_shadow_fb, \
 119         .cleanup_fb = drm_gem_cleanup_shadow_fb
 120
 121 int drm_gem_simple_kms_prepare_shadow_fb(struct drm_simple_display_pipe *pipe,
 122                                          struct drm_plane_state *plane_state);
 123 void drm_gem_simple_kms_cleanup_shadow_fb(struct drm_simple_display_pipe *pipe,
 124                                           struct drm_plane_state *plane_state);
 125 void drm_gem_simple_kms_reset_shadow_plane(struct drm_simple_display_pipe *pipe);
 126 struct drm_plane_state *
 127 drm_gem_simple_kms_duplicate_shadow_plane_state(struct drm_simple_display_pipe *pipe);
 128 void drm_gem_simple_kms_destroy_shadow_plane_state(struct drm_simple_display_pipe *pipe,
 129                                                    struct drm_plane_state *plane_state);
 130
 131 /**
 132  * DRM_GEM_SIMPLE_DISPLAY_PIPE_SHADOW_PLANE_FUNCS -
 133  *      Initializes struct drm_simple_display_pipe_funcs for shadow-buffered planes
 134  *
 135  * Drivers may use GEM BOs as shadow buffers over the framebuffer memory. This
 136  * macro initializes struct drm_simple_display_pipe_funcs to use the rsp helper
 137  * functions.
 138  */
 139 #define DRM_GEM_SIMPLE_DISPLAY_PIPE_SHADOW_PLANE_FUNCS \
 140         .prepare_fb = drm_gem_simple_kms_prepare_shadow_fb, \
 141         .cleanup_fb = drm_gem_simple_kms_cleanup_shadow_fb, \
 142         .reset_plane = drm_gem_simple_kms_reset_shadow_plane, \
 143         .duplicate_plane_state = drm_gem_simple_kms_duplicate_shadow_plane_state, \
 144         .destroy_plane_state = drm_gem_simple_kms_destroy_shadow_plane_state
 145
 146 #endif /* __DRM_GEM_ATOMIC_HELPER_H__ */