linux/include/drm/drm_simple_kms_helper.h
<<
>>
Prefs
   1/* SPDX-License-Identifier: GPL-2.0-or-later */
   2/*
   3 * Copyright (C) 2016 Noralf Tr\xC3\xB8nnes
   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_simple_display_pipe *pipe,
  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() for more
 104         * complex case. In case the hardware lacks vblank support entirely,
 105         * drivers can set &struct drm_crtc_state.no_vblank in
 106         * &struct drm_simple_display_pipe_funcs.check and let DRM's
 107         * atomic helper fake a vblank event.
 108         */
 109        void (*update)(struct drm_simple_display_pipe *pipe,
 110                       struct drm_plane_state *old_plane_state);
 111
 112        /**
 113         * @prepare_fb:
 114         *
 115         * Optional, called by &drm_plane_helper_funcs.prepare_fb.  Please read
 116         * the documentation for the &drm_plane_helper_funcs.prepare_fb hook for
 117         * more details.
 118         *
 119         * Drivers which always have their buffers pinned should use
 120         * drm_gem_simple_display_pipe_prepare_fb() for this hook.
 121         */
 122        int (*prepare_fb)(struct drm_simple_display_pipe *pipe,
 123                          struct drm_plane_state *plane_state);
 124
 125        /**
 126         * @cleanup_fb:
 127         *
 128         * Optional, called by &drm_plane_helper_funcs.cleanup_fb.  Please read
 129         * the documentation for the &drm_plane_helper_funcs.cleanup_fb hook for
 130         * more details.
 131         */
 132        void (*cleanup_fb)(struct drm_simple_display_pipe *pipe,
 133                           struct drm_plane_state *plane_state);
 134
 135        /**
 136         * @enable_vblank:
 137         *
 138         * Optional, called by &drm_crtc_funcs.enable_vblank. Please read
 139         * the documentation for the &drm_crtc_funcs.enable_vblank hook for
 140         * more details.
 141         */
 142        int (*enable_vblank)(struct drm_simple_display_pipe *pipe);
 143
 144        /**
 145         * @disable_vblank:
 146         *
 147         * Optional, called by &drm_crtc_funcs.disable_vblank. Please read
 148         * the documentation for the &drm_crtc_funcs.disable_vblank hook for
 149         * more details.
 150         */
 151        void (*disable_vblank)(struct drm_simple_display_pipe *pipe);
 152
 153        /**
 154         * @reset_plane:
 155         *
 156         * Optional, called by &drm_plane_funcs.reset. Please read the
 157         * documentation for the &drm_plane_funcs.reset hook for more details.
 158         */
 159        void (*reset_plane)(struct drm_simple_display_pipe *pipe);
 160
 161        /**
 162         * @duplicate_plane_state:
 163         *
 164         * Optional, called by &drm_plane_funcs.atomic_duplicate_state.  Please
 165         * read the documentation for the &drm_plane_funcs.atomic_duplicate_state
 166         * hook for more details.
 167         */
 168        struct drm_plane_state * (*duplicate_plane_state)(struct drm_simple_display_pipe *pipe);
 169
 170        /**
 171         * @destroy_plane_state:
 172         *
 173         * Optional, called by &drm_plane_funcs.atomic_destroy_state.  Please
 174         * read the documentation for the &drm_plane_funcs.atomic_destroy_state
 175         * hook for more details.
 176         */
 177        void (*destroy_plane_state)(struct drm_simple_display_pipe *pipe,
 178                                    struct drm_plane_state *plane_state);
 179};
 180
 181/**
 182 * struct drm_simple_display_pipe - simple display pipeline
 183 * @crtc: CRTC control structure
 184 * @plane: Plane control structure
 185 * @encoder: Encoder control structure
 186 * @connector: Connector control structure
 187 * @funcs: Pipeline control functions (optional)
 188 *
 189 * Simple display pipeline with plane, crtc and encoder collapsed into one
 190 * entity. It should be initialized by calling drm_simple_display_pipe_init().
 191 */
 192struct drm_simple_display_pipe {
 193        struct drm_crtc crtc;
 194        struct drm_plane plane;
 195        struct drm_encoder encoder;
 196        struct drm_connector *connector;
 197
 198        const struct drm_simple_display_pipe_funcs *funcs;
 199};
 200
 201int drm_simple_display_pipe_attach_bridge(struct drm_simple_display_pipe *pipe,
 202                                          struct drm_bridge *bridge);
 203
 204int drm_simple_display_pipe_init(struct drm_device *dev,
 205                        struct drm_simple_display_pipe *pipe,
 206                        const struct drm_simple_display_pipe_funcs *funcs,
 207                        const uint32_t *formats, unsigned int format_count,
 208                        const uint64_t *format_modifiers,
 209                        struct drm_connector *connector);
 210
 211int drm_simple_encoder_init(struct drm_device *dev,
 212                            struct drm_encoder *encoder,
 213                            int encoder_type);
 214
 215void *__drmm_simple_encoder_alloc(struct drm_device *dev, size_t size,
 216                                  size_t offset, int encoder_type);
 217
 218/**
 219 * drmm_simple_encoder_alloc - Allocate and initialize an encoder with basic
 220 *                             functionality.
 221 * @dev: drm device
 222 * @type: the type of the struct which contains struct &drm_encoder
 223 * @member: the name of the &drm_encoder within @type.
 224 * @encoder_type: user visible type of the encoder
 225 *
 226 * Allocates and initializes an encoder that has no further functionality.
 227 * Settings for possible CRTC and clones are left to their initial values.
 228 * Cleanup is automatically handled through registering drm_encoder_cleanup()
 229 * with drmm_add_action().
 230 *
 231 * Returns:
 232 * Pointer to new encoder, or ERR_PTR on failure.
 233 */
 234#define drmm_simple_encoder_alloc(dev, type, member, encoder_type) \
 235        ((type *)__drmm_simple_encoder_alloc(dev, sizeof(type), \
 236                                             offsetof(type, member), \
 237                                             encoder_type))
 238
 239#endif /* __LINUX_DRM_SIMPLE_KMS_HELPER_H */
 240