drivers/gpu/drm/drm_gem_atomic_helper.c

   1 // SPDX-License-Identifier: GPL-2.0-or-later
   2
   3 #include <linux/dma-resv.h>
   4 #include <linux/dma-fence-chain.h>
   5
   6 #include <drm/drm_atomic_state_helper.h>
   7 #include <drm/drm_atomic_uapi.h>
   8 #include <drm/drm_framebuffer.h>
   9 #include <drm/drm_gem.h>
  10 #include <drm/drm_gem_atomic_helper.h>
  11 #include <drm/drm_gem_framebuffer_helper.h>
  12 #include <drm/drm_simple_kms_helper.h>
  13
  14 #include "drm_internal.h"
  15
  16 /**
  17  * DOC: overview
  18  *
  19  * The GEM atomic helpers library implements generic atomic-commit
  20  * functions for drivers that use GEM objects. Currently, it provides
  21  * synchronization helpers, and plane state and framebuffer BO mappings
  22  * for planes with shadow buffers.
  23  *
  24  * Before scanout, a plane's framebuffer needs to be synchronized with
  25  * possible writers that draw into the framebuffer. All drivers should
  26  * call drm_gem_plane_helper_prepare_fb() from their implementation of
  27  * struct &drm_plane_helper.prepare_fb . It sets the plane's fence from
  28  * the framebuffer so that the DRM core can synchronize access automatically.
  29  *
  30  * drm_gem_plane_helper_prepare_fb() can also be used directly as
  31  * implementation of prepare_fb. For drivers based on
  32  * struct drm_simple_display_pipe, drm_gem_simple_display_pipe_prepare_fb()
  33  * provides equivalent functionality.
  34  *
  35  * .. code-block:: c
  36  *
  37  *      #include <drm/drm_gem_atomic_helper.h>
  38  *
  39  *      struct drm_plane_helper_funcs driver_plane_helper_funcs = {
  40  *              ...,
  41  *              . prepare_fb = drm_gem_plane_helper_prepare_fb,
  42  *      };
  43  *
  44  *      struct drm_simple_display_pipe_funcs driver_pipe_funcs = {
  45  *              ...,
  46  *              . prepare_fb = drm_gem_simple_display_pipe_prepare_fb,
  47  *      };
  48  *
  49  * A driver using a shadow buffer copies the content of the shadow buffers
  50  * into the HW's framebuffer memory during an atomic update. This requires
  51  * a mapping of the shadow buffer into kernel address space. The mappings
  52  * cannot be established by commit-tail functions, such as atomic_update,
  53  * as this would violate locking rules around dma_buf_vmap().
  54  *
  55  * The helpers for shadow-buffered planes establish and release mappings,
  56  * and provide struct drm_shadow_plane_state, which stores the plane's mapping
  57  * for commit-tail functions.
  58  *
  59  * Shadow-buffered planes can easily be enabled by using the provided macros
  60  * %DRM_GEM_SHADOW_PLANE_FUNCS and %DRM_GEM_SHADOW_PLANE_HELPER_FUNCS.
  61  * These macros set up the plane and plane-helper callbacks to point to the
  62  * shadow-buffer helpers.
  63  *
  64  * .. code-block:: c
  65  *
  66  *      #include <drm/drm_gem_atomic_helper.h>
  67  *
  68  *      struct drm_plane_funcs driver_plane_funcs = {
  69  *              ...,
  70  *              DRM_GEM_SHADOW_PLANE_FUNCS,
  71  *      };
  72  *
  73  *      struct drm_plane_helper_funcs driver_plane_helper_funcs = {
  74  *              ...,
  75  *              DRM_GEM_SHADOW_PLANE_HELPER_FUNCS,
  76  *      };
  77  *
  78  * In the driver's atomic-update function, shadow-buffer mappings are available
  79  * from the plane state. Use to_drm_shadow_plane_state() to upcast from
  80  * struct drm_plane_state.
  81  *
  82  * .. code-block:: c
  83  *
  84  *      void driver_plane_atomic_update(struct drm_plane *plane,
  85  *                                      struct drm_plane_state *old_plane_state)
  86  *      {
  87  *              struct drm_plane_state *plane_state = plane->state;
  88  *              struct drm_shadow_plane_state *shadow_plane_state =
  89  *                      to_drm_shadow_plane_state(plane_state);
  90  *
  91  *              // access shadow buffer via shadow_plane_state->map
  92  *      }
  93  *
  94  * A mapping address for each of the framebuffer's buffer object is stored in
  95  * struct &drm_shadow_plane_state.map. The mappings are valid while the state
  96  * is being used.
  97  *
  98  * Drivers that use struct drm_simple_display_pipe can use
  99  * %DRM_GEM_SIMPLE_DISPLAY_PIPE_SHADOW_PLANE_FUNCS to initialize the rsp
 100  * callbacks. Access to shadow-buffer mappings is similar to regular
 101  * atomic_update.
 102  *
 103  * .. code-block:: c
 104  *
 105  *      struct drm_simple_display_pipe_funcs driver_pipe_funcs = {
 106  *              ...,
 107  *              DRM_GEM_SIMPLE_DISPLAY_PIPE_SHADOW_PLANE_FUNCS,
 108  *      };
 109  *
 110  *      void driver_pipe_enable(struct drm_simple_display_pipe *pipe,
 111  *                              struct drm_crtc_state *crtc_state,
 112  *                              struct drm_plane_state *plane_state)
 113  *      {
 114  *              struct drm_shadow_plane_state *shadow_plane_state =
 115  *                      to_drm_shadow_plane_state(plane_state);
 116  *
 117  *              // access shadow buffer via shadow_plane_state->map
 118  *      }
 119  */
 120
 121 /*
 122  * Plane Helpers
 123  */
 124
 125 /**
 126  * drm_gem_plane_helper_prepare_fb() - Prepare a GEM backed framebuffer
 127  * @plane: Plane
 128  * @state: Plane state the fence will be attached to
 129  *
 130  * This function extracts the exclusive fence from &drm_gem_object.resv and
 131  * attaches it to plane state for the atomic helper to wait on. This is
 132  * necessary to correctly implement implicit synchronization for any buffers
 133  * shared as a struct &dma_buf. This function can be used as the
 134  * &drm_plane_helper_funcs.prepare_fb callback.
 135  *
 136  * There is no need for &drm_plane_helper_funcs.cleanup_fb hook for simple
 137  * GEM based framebuffer drivers which have their buffers always pinned in
 138  * memory.
 139  *
 140  * This function is the default implementation for GEM drivers of
 141  * &drm_plane_helper_funcs.prepare_fb if no callback is provided.
 142  */
 143 int drm_gem_plane_helper_prepare_fb(struct drm_plane *plane,
 144                                     struct drm_plane_state *state)
 145 {
 146         struct dma_fence *fence = dma_fence_get(state->fence);
 147         enum dma_resv_usage usage;
 148         size_t i;
 149         int ret;
 150
 151         if (!state->fb)
 152                 return 0;
 153
 154         /*
 155          * Only add the kernel fences here if there is already a fence set via
 156          * explicit fencing interfaces on the atomic ioctl.
 157          *
 158          * This way explicit fencing can be used to overrule implicit fencing,
 159          * which is important to make explicit fencing use-cases work: One
 160          * example is using one buffer for 2 screens with different refresh
 161          * rates. Implicit fencing will clamp rendering to the refresh rate of
 162          * the slower screen, whereas explicit fence allows 2 independent
 163          * render and display loops on a single buffer. If a driver allows
 164          * obeys both implicit and explicit fences for plane updates, then it
 165          * will break all the benefits of explicit fencing.
 166          */
 167         usage = fence ? DMA_RESV_USAGE_KERNEL : DMA_RESV_USAGE_WRITE;
 168
 169         for (i = 0; i < state->fb->format->num_planes; ++i) {
 170                 struct drm_gem_object *obj = drm_gem_fb_get_obj(state->fb, i);
 171                 struct dma_fence *new;
 172
 173                 if (!obj) {
 174                         ret = -EINVAL;
 175                         goto error;
 176                 }
 177
 178                 ret = dma_resv_get_singleton(obj->resv, usage, &new);
 179                 if (ret)
 180                         goto error;
 181
 182                 if (new && fence) {
 183                         struct dma_fence_chain *chain = dma_fence_chain_alloc();
 184
 185                         if (!chain) {
 186                                 ret = -ENOMEM;
 187                                 goto error;
 188                         }
 189
 190                         dma_fence_chain_init(chain, fence, new, 1);
 191                         fence = &chain->base;
 192
 193                 } else if (new) {
 194                         fence = new;
 195                 }
 196         }
 197
 198         dma_fence_put(state->fence);
 199         state->fence = fence;
 200         return 0;
 201
 202 error:
 203         dma_fence_put(fence);
 204         return ret;
 205 }
 206 EXPORT_SYMBOL_GPL(drm_gem_plane_helper_prepare_fb);
 207
 208 /**
 209  * drm_gem_simple_display_pipe_prepare_fb - prepare_fb helper for &drm_simple_display_pipe
 210  * @pipe: Simple display pipe
 211  * @plane_state: Plane state
 212  *
 213  * This function uses drm_gem_plane_helper_prepare_fb() to extract the fences
 214  * from &drm_gem_object.resv and attaches them to the plane state for the atomic
 215  * helper to wait on. This is necessary to correctly implement implicit
 216  * synchronization for any buffers shared as a struct &dma_buf. Drivers can use
 217  * this as their &drm_simple_display_pipe_funcs.prepare_fb callback.
 218  *
 219  * See drm_gem_plane_helper_prepare_fb() for a discussion of implicit and
 220  * explicit fencing in atomic modeset updates.
 221  */
 222 int drm_gem_simple_display_pipe_prepare_fb(struct drm_simple_display_pipe *pipe,
 223                                            struct drm_plane_state *plane_state)
 224 {
 225         return drm_gem_plane_helper_prepare_fb(&pipe->plane, plane_state);
 226 }
 227 EXPORT_SYMBOL(drm_gem_simple_display_pipe_prepare_fb);
 228
 229 /*
 230  * Shadow-buffered Planes
 231  */
 232
 233 /**
 234  * __drm_gem_duplicate_shadow_plane_state - duplicates shadow-buffered plane state
 235  * @plane: the plane
 236  * @new_shadow_plane_state: the new shadow-buffered plane state
 237  *
 238  * This function duplicates shadow-buffered plane state. This is helpful for drivers
 239  * that subclass struct drm_shadow_plane_state.
 240  *
 241  * The function does not duplicate existing mappings of the shadow buffers.
 242  * Mappings are maintained during the atomic commit by the plane's prepare_fb
 243  * and cleanup_fb helpers. See drm_gem_prepare_shadow_fb() and drm_gem_cleanup_shadow_fb()
 244  * for corresponding helpers.
 245  */
 246 void
 247 __drm_gem_duplicate_shadow_plane_state(struct drm_plane *plane,
 248                                        struct drm_shadow_plane_state *new_shadow_plane_state)
 249 {
 250         __drm_atomic_helper_plane_duplicate_state(plane, &new_shadow_plane_state->base);
 251 }
 252 EXPORT_SYMBOL(__drm_gem_duplicate_shadow_plane_state);
 253
 254 /**
 255  * drm_gem_duplicate_shadow_plane_state - duplicates shadow-buffered plane state
 256  * @plane: the plane
 257  *
 258  * This function implements struct &drm_plane_funcs.atomic_duplicate_state for
 259  * shadow-buffered planes. It assumes the existing state to be of type
 260  * struct drm_shadow_plane_state and it allocates the new state to be of this
 261  * type.
 262  *
 263  * The function does not duplicate existing mappings of the shadow buffers.
 264  * Mappings are maintained during the atomic commit by the plane's prepare_fb
 265  * and cleanup_fb helpers. See drm_gem_prepare_shadow_fb() and drm_gem_cleanup_shadow_fb()
 266  * for corresponding helpers.
 267  *
 268  * Returns:
 269  * A pointer to a new plane state on success, or NULL otherwise.
 270  */
 271 struct drm_plane_state *
 272 drm_gem_duplicate_shadow_plane_state(struct drm_plane *plane)
 273 {
 274         struct drm_plane_state *plane_state = plane->state;
 275         struct drm_shadow_plane_state *new_shadow_plane_state;
 276
 277         if (!plane_state)
 278                 return NULL;
 279
 280         new_shadow_plane_state = kzalloc(sizeof(*new_shadow_plane_state), GFP_KERNEL);
 281         if (!new_shadow_plane_state)
 282                 return NULL;
 283         __drm_gem_duplicate_shadow_plane_state(plane, new_shadow_plane_state);
 284
 285         return &new_shadow_plane_state->base;
 286 }
 287 EXPORT_SYMBOL(drm_gem_duplicate_shadow_plane_state);
 288
 289 /**
 290  * __drm_gem_destroy_shadow_plane_state - cleans up shadow-buffered plane state
 291  * @shadow_plane_state: the shadow-buffered plane state
 292  *
 293  * This function cleans up shadow-buffered plane state. Helpful for drivers that
 294  * subclass struct drm_shadow_plane_state.
 295  */
 296 void __drm_gem_destroy_shadow_plane_state(struct drm_shadow_plane_state *shadow_plane_state)
 297 {
 298         __drm_atomic_helper_plane_destroy_state(&shadow_plane_state->base);
 299 }
 300 EXPORT_SYMBOL(__drm_gem_destroy_shadow_plane_state);
 301
 302 /**
 303  * drm_gem_destroy_shadow_plane_state - deletes shadow-buffered plane state
 304  * @plane: the plane
 305  * @plane_state: the plane state of type struct drm_shadow_plane_state
 306  *
 307  * This function implements struct &drm_plane_funcs.atomic_destroy_state
 308  * for shadow-buffered planes. It expects that mappings of shadow buffers
 309  * have been released already.
 310  */
 311 void drm_gem_destroy_shadow_plane_state(struct drm_plane *plane,
 312                                         struct drm_plane_state *plane_state)
 313 {
 314         struct drm_shadow_plane_state *shadow_plane_state =
 315                 to_drm_shadow_plane_state(plane_state);
 316
 317         __drm_gem_destroy_shadow_plane_state(shadow_plane_state);
 318         kfree(shadow_plane_state);
 319 }
 320 EXPORT_SYMBOL(drm_gem_destroy_shadow_plane_state);
 321
 322 /**
 323  * __drm_gem_reset_shadow_plane - resets a shadow-buffered plane
 324  * @plane: the plane
 325  * @shadow_plane_state: the shadow-buffered plane state
 326  *
 327  * This function resets state for shadow-buffered planes. Helpful
 328  * for drivers that subclass struct drm_shadow_plane_state.
 329  */
 330 void __drm_gem_reset_shadow_plane(struct drm_plane *plane,
 331                                   struct drm_shadow_plane_state *shadow_plane_state)
 332 {
 333         __drm_atomic_helper_plane_reset(plane, &shadow_plane_state->base);
 334 }
 335 EXPORT_SYMBOL(__drm_gem_reset_shadow_plane);
 336
 337 /**
 338  * drm_gem_reset_shadow_plane - resets a shadow-buffered plane
 339  * @plane: the plane
 340  *
 341  * This function implements struct &drm_plane_funcs.reset_plane for
 342  * shadow-buffered planes. It assumes the current plane state to be
 343  * of type struct drm_shadow_plane and it allocates the new state of
 344  * this type.
 345  */
 346 void drm_gem_reset_shadow_plane(struct drm_plane *plane)
 347 {
 348         struct drm_shadow_plane_state *shadow_plane_state;
 349
 350         if (plane->state) {
 351                 drm_gem_destroy_shadow_plane_state(plane, plane->state);
 352                 plane->state = NULL; /* must be set to NULL here */
 353         }
 354
 355         shadow_plane_state = kzalloc(sizeof(*shadow_plane_state), GFP_KERNEL);
 356         if (!shadow_plane_state)
 357                 return;
 358         __drm_gem_reset_shadow_plane(plane, shadow_plane_state);
 359 }
 360 EXPORT_SYMBOL(drm_gem_reset_shadow_plane);
 361
 362 /**
 363  * drm_gem_begin_shadow_fb_access - prepares shadow framebuffers for CPU access
 364  * @plane: the plane
 365  * @plane_state: the plane state of type struct drm_shadow_plane_state
 366  *
 367  * This function implements struct &drm_plane_helper_funcs.begin_fb_access. It
 368  * maps all buffer objects of the plane's framebuffer into kernel address
 369  * space and stores them in struct &drm_shadow_plane_state.map. The first data
 370  * bytes are available in struct &drm_shadow_plane_state.data.
 371  *
 372  * See drm_gem_end_shadow_fb_access() for cleanup.
 373  *
 374  * Returns:
 375  * 0 on success, or a negative errno code otherwise.
 376  */
 377 int drm_gem_begin_shadow_fb_access(struct drm_plane *plane, struct drm_plane_state *plane_state)
 378 {
 379         struct drm_shadow_plane_state *shadow_plane_state = to_drm_shadow_plane_state(plane_state);
 380         struct drm_framebuffer *fb = plane_state->fb;
 381
 382         if (!fb)
 383                 return 0;
 384
 385         return drm_gem_fb_vmap(fb, shadow_plane_state->map, shadow_plane_state->data);
 386 }
 387 EXPORT_SYMBOL(drm_gem_begin_shadow_fb_access);
 388
 389 /**
 390  * drm_gem_end_shadow_fb_access - releases shadow framebuffers from CPU access
 391  * @plane: the plane
 392  * @plane_state: the plane state of type struct drm_shadow_plane_state
 393  *
 394  * This function implements struct &drm_plane_helper_funcs.end_fb_access. It
 395  * undoes all effects of drm_gem_begin_shadow_fb_access() in reverse order.
 396  *
 397  * See drm_gem_begin_shadow_fb_access() for more information.
 398  */
 399 void drm_gem_end_shadow_fb_access(struct drm_plane *plane, struct drm_plane_state *plane_state)
 400 {
 401         struct drm_shadow_plane_state *shadow_plane_state = to_drm_shadow_plane_state(plane_state);
 402         struct drm_framebuffer *fb = plane_state->fb;
 403
 404         if (!fb)
 405                 return;
 406
 407         drm_gem_fb_vunmap(fb, shadow_plane_state->map);
 408 }
 409 EXPORT_SYMBOL(drm_gem_end_shadow_fb_access);
 410
 411 /**
 412  * drm_gem_simple_kms_begin_shadow_fb_access - prepares shadow framebuffers for CPU access
 413  * @pipe: the simple display pipe
 414  * @plane_state: the plane state of type struct drm_shadow_plane_state
 415  *
 416  * This function implements struct drm_simple_display_funcs.begin_fb_access.
 417  *
 418  * See drm_gem_begin_shadow_fb_access() for details and
 419  * drm_gem_simple_kms_cleanup_shadow_fb() for cleanup.
 420  *
 421  * Returns:
 422  * 0 on success, or a negative errno code otherwise.
 423  */
 424 int drm_gem_simple_kms_begin_shadow_fb_access(struct drm_simple_display_pipe *pipe,
 425                                               struct drm_plane_state *plane_state)
 426 {
 427         return drm_gem_begin_shadow_fb_access(&pipe->plane, plane_state);
 428 }
 429 EXPORT_SYMBOL(drm_gem_simple_kms_begin_shadow_fb_access);
 430
 431 /**
 432  * drm_gem_simple_kms_end_shadow_fb_access - releases shadow framebuffers from CPU access
 433  * @pipe: the simple display pipe
 434  * @plane_state: the plane state of type struct drm_shadow_plane_state
 435  *
 436  * This function implements struct drm_simple_display_funcs.end_fb_access.
 437  * It undoes all effects of drm_gem_simple_kms_begin_shadow_fb_access() in
 438  * reverse order.
 439  *
 440  * See drm_gem_simple_kms_begin_shadow_fb_access().
 441  */
 442 void drm_gem_simple_kms_end_shadow_fb_access(struct drm_simple_display_pipe *pipe,
 443                                              struct drm_plane_state *plane_state)
 444 {
 445         drm_gem_end_shadow_fb_access(&pipe->plane, plane_state);
 446 }
 447 EXPORT_SYMBOL(drm_gem_simple_kms_end_shadow_fb_access);
 448
 449 /**
 450  * drm_gem_simple_kms_reset_shadow_plane - resets a shadow-buffered plane
 451  * @pipe: the simple display pipe
 452  *
 453  * This function implements struct drm_simple_display_funcs.reset_plane
 454  * for shadow-buffered planes.
 455  */
 456 void drm_gem_simple_kms_reset_shadow_plane(struct drm_simple_display_pipe *pipe)
 457 {
 458         drm_gem_reset_shadow_plane(&pipe->plane);
 459 }
 460 EXPORT_SYMBOL(drm_gem_simple_kms_reset_shadow_plane);
 461
 462 /**
 463  * drm_gem_simple_kms_duplicate_shadow_plane_state - duplicates shadow-buffered plane state
 464  * @pipe: the simple display pipe
 465  *
 466  * This function implements struct drm_simple_display_funcs.duplicate_plane_state
 467  * for shadow-buffered planes. It does not duplicate existing mappings of the shadow
 468  * buffers. Mappings are maintained during the atomic commit by the plane's prepare_fb
 469  * and cleanup_fb helpers.
 470  *
 471  * Returns:
 472  * A pointer to a new plane state on success, or NULL otherwise.
 473  */
 474 struct drm_plane_state *
 475 drm_gem_simple_kms_duplicate_shadow_plane_state(struct drm_simple_display_pipe *pipe)
 476 {
 477         return drm_gem_duplicate_shadow_plane_state(&pipe->plane);
 478 }
 479 EXPORT_SYMBOL(drm_gem_simple_kms_duplicate_shadow_plane_state);
 480
 481 /**
 482  * drm_gem_simple_kms_destroy_shadow_plane_state - resets shadow-buffered plane state
 483  * @pipe: the simple display pipe
 484  * @plane_state: the plane state of type struct drm_shadow_plane_state
 485  *
 486  * This function implements struct drm_simple_display_funcs.destroy_plane_state
 487  * for shadow-buffered planes. It expects that mappings of shadow buffers
 488  * have been released already.
 489  */
 490 void drm_gem_simple_kms_destroy_shadow_plane_state(struct drm_simple_display_pipe *pipe,
 491                                                    struct drm_plane_state *plane_state)
 492 {
 493         drm_gem_destroy_shadow_plane_state(&pipe->plane, plane_state);
 494 }
 495 EXPORT_SYMBOL(drm_gem_simple_kms_destroy_shadow_plane_state);