LXR linux/include/drm/drm_simple_kms

   1/* SPDX-License-Identifier: GPL-2.0-or-later */
   2/*
   3 * Copyright (C) 2016 Noralf Trønnes
   4 */
   5
   6#ifndef __LINUX_DRM_SIMPLE_KMS_HELPER_H
   7#define __LINUX_DRM_SIMPLE_KMS_HELPER_H
   8
   9#include <drm/drm_crtc.h>
  10#include <drm/drm_encoder.h>
  11#include <drm/drm_plane.h>
  12
  13struct drm_simple_display_pipe;
  14
  15/**
  16 * struct drm_simple_display_pipe_funcs - helper operations for a simple
  17 *                                        display pipeline
  18 */
  19struct drm_simple_display_pipe_funcs {
  20        /**
  21         * @mode_valid:
  22         *
  23         * This callback is used to check if a specific mode is valid in the
  24         * crtc used in this simple display pipe. This should be implemented
  25         * if the display pipe has some sort of restriction in the modes
  26         * it can display. For example, a given display pipe may be responsible
  27         * to set a clock value. If the clock can not produce all the values
  28         * for the available modes then this callback can be used to restrict
  29         * the number of modes to only the ones that can be displayed. Another
  30         * reason can be bandwidth mitigation: the memory port on the display
  31         * controller can have bandwidth limitations not allowing pixel data
  32         * to be fetched at any rate.
  33         *
  34         * This hook is used by the probe helpers to filter the mode list in
  35         * drm_helper_probe_single_connector_modes(), and it is used by the
  36         * atomic helpers to validate modes supplied by userspace in
  37         * drm_atomic_helper_check_modeset().
  38         *
  39         * This function is optional.
  40         *
  41         * NOTE:
  42         *
  43         * Since this function is both called from the check phase of an atomic
  44         * commit, and the mode validation in the probe paths it is not allowed
  45         * to look at anything else but the passed-in mode, and validate it
  46         * against configuration-invariant hardware constraints.
  47         *
  48         * RETURNS:
  49         *
  50         * drm_mode_status Enum
  51         */
  52        enum drm_mode_status (*mode_valid)(struct drm_crtc *crtc,
  53                                           const struct drm_display_mode *mode);
  54
  55        /**
  56         * @enable:
  57         *
  58         * This function should be used to enable the pipeline.
  59         * It is called when the underlying crtc is enabled.
  60         * This hook is optional.
  61         */
  62        void (*enable)(struct drm_simple_display_pipe *pipe,
  63                       struct drm_crtc_state *crtc_state,
  64                       struct drm_plane_state *plane_state);
  65        /**
  66         * @disable:
  67         *
  68         * This function should be used to disable the pipeline.
  69         * It is called when the underlying crtc is disabled.
  70         * This hook is optional.
  71         */
  72        void (*disable)(struct drm_simple_display_pipe *pipe);
  73
  74        /**
  75         * @check:
  76         *
  77         * This function is called in the check phase of an atomic update,
  78         * specifically when the underlying plane is checked.
  79         * The simple display pipeline helpers already check that the plane is
  80         * not scaled, fills the entire visible area and is always enabled
  81         * when the crtc is also enabled.
  82         * This hook is optional.
  83         *
  84         * RETURNS:
  85         *
  86         * 0 on success, -EINVAL if the state or the transition can't be
  87         * supported, -ENOMEM on memory allocation failure and -EDEADLK if an
  88         * attempt to obtain another state object ran into a &drm_modeset_lock
  89         * deadlock.
  90         */
  91        int (*check)(struct drm_simple_display_pipe *pipe,
  92                     struct drm_plane_state *plane_state,
  93                     struct drm_crtc_state *crtc_state);
  94        /**
  95         * @update:
  96         *
  97         * This function is called when the underlying plane state is updated.
  98         * This hook is optional.
  99         *
 100         * This is the function drivers should submit the
 101         * &drm_pending_vblank_event from. Using either
 102         * drm_crtc_arm_vblank_event(), when the driver supports vblank
 103         * interrupt handling, or drm_crtc_send_vblank_event() directly in case
 104         * the hardware lacks vblank support entirely.
 105         */
 106        void (*update)(struct drm_simple_display_pipe *pipe,
 107                       struct drm_plane_state *old_plane_state);
 108
 109        /**
 110         * @prepare_fb:
 111         *
 112         * Optional, called by &drm_plane_helper_funcs.prepare_fb.  Please read
 113         * the documentation for the &drm_plane_helper_funcs.prepare_fb hook for
 114         * more details.
 115         *
 116         * Drivers which always have their buffers pinned should use
 117         * drm_gem_fb_simple_display_pipe_prepare_fb() for this hook.
 118         */
 119        int (*prepare_fb)(struct drm_simple_display_pipe *pipe,
 120                          struct drm_plane_state *plane_state);
 121
 122        /**
 123         * @cleanup_fb:
 124         *
 125         * Optional, called by &drm_plane_helper_funcs.cleanup_fb.  Please read
 126         * the documentation for the &drm_plane_helper_funcs.cleanup_fb hook for
 127         * more details.
 128         */
 129        void (*cleanup_fb)(struct drm_simple_display_pipe *pipe,
 130                           struct drm_plane_state *plane_state);
 131
 132        /**
 133         * @enable_vblank:
 134         *
 135         * Optional, called by &drm_crtc_funcs.enable_vblank. Please read
 136         * the documentation for the &drm_crtc_funcs.enable_vblank hook for
 137         * more details.
 138         */
 139        int (*enable_vblank)(struct drm_simple_display_pipe *pipe);
 140
 141        /**
 142         * @disable_vblank:
 143         *
 144         * Optional, called by &drm_crtc_funcs.disable_vblank. Please read
 145         * the documentation for the &drm_crtc_funcs.disable_vblank hook for
 146         * more details.
 147         */
 148        void (*disable_vblank)(struct drm_simple_display_pipe *pipe);
 149};
 150
 151/**
 152 * struct drm_simple_display_pipe - simple display pipeline
 153 * @crtc: CRTC control structure
 154 * @plane: Plane control structure
 155 * @encoder: Encoder control structure
 156 * @connector: Connector control structure
 157 * @funcs: Pipeline control functions (optional)
 158 *
 159 * Simple display pipeline with plane, crtc and encoder collapsed into one
 160 * entity. It should be initialized by calling drm_simple_display_pipe_init().
 161 */
 162struct drm_simple_display_pipe {
 163        struct drm_crtc crtc;
 164        struct drm_plane plane;
 165        struct drm_encoder encoder;
 166        struct drm_connector *connector;
 167
 168        const struct drm_simple_display_pipe_funcs *funcs;
 169};
 170
 171int drm_simple_display_pipe_attach_bridge(struct drm_simple_display_pipe *pipe,
 172                                          struct drm_bridge *bridge);
 173
 174int drm_simple_display_pipe_init(struct drm_device *dev,
 175                        struct drm_simple_display_pipe *pipe,
 176                        const struct drm_simple_display_pipe_funcs *funcs,
 177                        const uint32_t *formats, unsigned int format_count,
 178                        const uint64_t *format_modifiers,
 179                        struct drm_connector *connector);
 180
 181#endif /* __LINUX_DRM_SIMPLE_KMS_HELPER_H */
 182