include/drm/drm_simple_kms_helper.h

0001 /* SPDX-License-Identifier: GPL-2.0-or-later */
0002 /*
0003  * Copyright (C) 2016 Noralf Trønnes
0004  */
0005
0006 #ifndef __LINUX_DRM_SIMPLE_KMS_HELPER_H
0007 #define __LINUX_DRM_SIMPLE_KMS_HELPER_H
0008
0009 #include <drm/drm_crtc.h>
0010 #include <drm/drm_encoder.h>
0011 #include <drm/drm_plane.h>
0012
0013 struct drm_simple_display_pipe;
0014
0015 /**
0016  * struct drm_simple_display_pipe_funcs - helper operations for a simple
0017  *                                        display pipeline
0018  */
0019 struct drm_simple_display_pipe_funcs {
0020     /**
0021      * @mode_valid:
0022      *
0023      * This callback is used to check if a specific mode is valid in the
0024      * crtc used in this simple display pipe. This should be implemented
0025      * if the display pipe has some sort of restriction in the modes
0026      * it can display. For example, a given display pipe may be responsible
0027      * to set a clock value. If the clock can not produce all the values
0028      * for the available modes then this callback can be used to restrict
0029      * the number of modes to only the ones that can be displayed. Another
0030      * reason can be bandwidth mitigation: the memory port on the display
0031      * controller can have bandwidth limitations not allowing pixel data
0032      * to be fetched at any rate.
0033      *
0034      * This hook is used by the probe helpers to filter the mode list in
0035      * drm_helper_probe_single_connector_modes(), and it is used by the
0036      * atomic helpers to validate modes supplied by userspace in
0037      * drm_atomic_helper_check_modeset().
0038      *
0039      * This function is optional.
0040      *
0041      * NOTE:
0042      *
0043      * Since this function is both called from the check phase of an atomic
0044      * commit, and the mode validation in the probe paths it is not allowed
0045      * to look at anything else but the passed-in mode, and validate it
0046      * against configuration-invariant hardware constraints.
0047      *
0048      * RETURNS:
0049      *
0050      * drm_mode_status Enum
0051      */
0052     enum drm_mode_status (*mode_valid)(struct drm_simple_display_pipe *pipe,
0053                        const struct drm_display_mode *mode);
0054
0055     /**
0056      * @enable:
0057      *
0058      * This function should be used to enable the pipeline.
0059      * It is called when the underlying crtc is enabled.
0060      * This hook is optional.
0061      */
0062     void (*enable)(struct drm_simple_display_pipe *pipe,
0063                struct drm_crtc_state *crtc_state,
0064                struct drm_plane_state *plane_state);
0065     /**
0066      * @disable:
0067      *
0068      * This function should be used to disable the pipeline.
0069      * It is called when the underlying crtc is disabled.
0070      * This hook is optional.
0071      */
0072     void (*disable)(struct drm_simple_display_pipe *pipe);
0073
0074     /**
0075      * @check:
0076      *
0077      * This function is called in the check phase of an atomic update,
0078      * specifically when the underlying plane is checked.
0079      * The simple display pipeline helpers already check that the plane is
0080      * not scaled, fills the entire visible area and is always enabled
0081      * when the crtc is also enabled.
0082      * This hook is optional.
0083      *
0084      * RETURNS:
0085      *
0086      * 0 on success, -EINVAL if the state or the transition can't be
0087      * supported, -ENOMEM on memory allocation failure and -EDEADLK if an
0088      * attempt to obtain another state object ran into a &drm_modeset_lock
0089      * deadlock.
0090      */
0091     int (*check)(struct drm_simple_display_pipe *pipe,
0092              struct drm_plane_state *plane_state,
0093              struct drm_crtc_state *crtc_state);
0094     /**
0095      * @update:
0096      *
0097      * This function is called when the underlying plane state is updated.
0098      * This hook is optional.
0099      *
0100      * This is the function drivers should submit the
0101      * &drm_pending_vblank_event from. Using either
0102      * drm_crtc_arm_vblank_event(), when the driver supports vblank
0103      * interrupt handling, or drm_crtc_send_vblank_event() for more
0104      * complex case. In case the hardware lacks vblank support entirely,
0105      * drivers can set &struct drm_crtc_state.no_vblank in
0106      * &struct drm_simple_display_pipe_funcs.check and let DRM's
0107      * atomic helper fake a vblank event.
0108      */
0109     void (*update)(struct drm_simple_display_pipe *pipe,
0110                struct drm_plane_state *old_plane_state);
0111
0112     /**
0113      * @prepare_fb:
0114      *
0115      * Optional, called by &drm_plane_helper_funcs.prepare_fb.  Please read
0116      * the documentation for the &drm_plane_helper_funcs.prepare_fb hook for
0117      * more details.
0118      *
0119      * For GEM drivers who neither have a @prepare_fb nor @cleanup_fb hook
0120      * set drm_gem_simple_display_pipe_prepare_fb() is called automatically
0121      * to implement this. Other drivers which need additional plane
0122      * processing can call drm_gem_simple_display_pipe_prepare_fb() from
0123      * their @prepare_fb hook.
0124      */
0125     int (*prepare_fb)(struct drm_simple_display_pipe *pipe,
0126               struct drm_plane_state *plane_state);
0127
0128     /**
0129      * @cleanup_fb:
0130      *
0131      * Optional, called by &drm_plane_helper_funcs.cleanup_fb.  Please read
0132      * the documentation for the &drm_plane_helper_funcs.cleanup_fb hook for
0133      * more details.
0134      */
0135     void (*cleanup_fb)(struct drm_simple_display_pipe *pipe,
0136                struct drm_plane_state *plane_state);
0137
0138     /**
0139      * @enable_vblank:
0140      *
0141      * Optional, called by &drm_crtc_funcs.enable_vblank. Please read
0142      * the documentation for the &drm_crtc_funcs.enable_vblank hook for
0143      * more details.
0144      */
0145     int (*enable_vblank)(struct drm_simple_display_pipe *pipe);
0146
0147     /**
0148      * @disable_vblank:
0149      *
0150      * Optional, called by &drm_crtc_funcs.disable_vblank. Please read
0151      * the documentation for the &drm_crtc_funcs.disable_vblank hook for
0152      * more details.
0153      */
0154     void (*disable_vblank)(struct drm_simple_display_pipe *pipe);
0155
0156     /**
0157      * @reset_crtc:
0158      *
0159      * Optional, called by &drm_crtc_funcs.reset. Please read the
0160      * documentation for the &drm_crtc_funcs.reset hook for more details.
0161      */
0162     void (*reset_crtc)(struct drm_simple_display_pipe *pipe);
0163
0164     /**
0165      * @duplicate_crtc_state:
0166      *
0167      * Optional, called by &drm_crtc_funcs.atomic_duplicate_state. Please
0168      * read the documentation for the &drm_crtc_funcs.atomic_duplicate_state
0169      * hook for more details.
0170      */
0171     struct drm_crtc_state * (*duplicate_crtc_state)(struct drm_simple_display_pipe *pipe);
0172
0173     /**
0174      * @destroy_crtc_state:
0175      *
0176      * Optional, called by &drm_crtc_funcs.atomic_destroy_state. Please
0177      * read the documentation for the &drm_crtc_funcs.atomic_destroy_state
0178      * hook for more details.
0179      */
0180     void (*destroy_crtc_state)(struct drm_simple_display_pipe *pipe,
0181                    struct drm_crtc_state *crtc_state);
0182
0183     /**
0184      * @reset_plane:
0185      *
0186      * Optional, called by &drm_plane_funcs.reset. Please read the
0187      * documentation for the &drm_plane_funcs.reset hook for more details.
0188      */
0189     void (*reset_plane)(struct drm_simple_display_pipe *pipe);
0190
0191     /**
0192      * @duplicate_plane_state:
0193      *
0194      * Optional, called by &drm_plane_funcs.atomic_duplicate_state.  Please
0195      * read the documentation for the &drm_plane_funcs.atomic_duplicate_state
0196      * hook for more details.
0197      */
0198     struct drm_plane_state * (*duplicate_plane_state)(struct drm_simple_display_pipe *pipe);
0199
0200     /**
0201      * @destroy_plane_state:
0202      *
0203      * Optional, called by &drm_plane_funcs.atomic_destroy_state.  Please
0204      * read the documentation for the &drm_plane_funcs.atomic_destroy_state
0205      * hook for more details.
0206      */
0207     void (*destroy_plane_state)(struct drm_simple_display_pipe *pipe,
0208                     struct drm_plane_state *plane_state);
0209 };
0210
0211 /**
0212  * struct drm_simple_display_pipe - simple display pipeline
0213  * @crtc: CRTC control structure
0214  * @plane: Plane control structure
0215  * @encoder: Encoder control structure
0216  * @connector: Connector control structure
0217  * @funcs: Pipeline control functions (optional)
0218  *
0219  * Simple display pipeline with plane, crtc and encoder collapsed into one
0220  * entity. It should be initialized by calling drm_simple_display_pipe_init().
0221  */
0222 struct drm_simple_display_pipe {
0223     struct drm_crtc crtc;
0224     struct drm_plane plane;
0225     struct drm_encoder encoder;
0226     struct drm_connector *connector;
0227
0228     const struct drm_simple_display_pipe_funcs *funcs;
0229 };
0230
0231 int drm_simple_display_pipe_attach_bridge(struct drm_simple_display_pipe *pipe,
0232                       struct drm_bridge *bridge);
0233
0234 int drm_simple_display_pipe_init(struct drm_device *dev,
0235             struct drm_simple_display_pipe *pipe,
0236             const struct drm_simple_display_pipe_funcs *funcs,
0237             const uint32_t *formats, unsigned int format_count,
0238             const uint64_t *format_modifiers,
0239             struct drm_connector *connector);
0240
0241 int drm_simple_encoder_init(struct drm_device *dev,
0242                 struct drm_encoder *encoder,
0243                 int encoder_type);
0244
0245 void *__drmm_simple_encoder_alloc(struct drm_device *dev, size_t size,
0246                   size_t offset, int encoder_type);
0247
0248 /**
0249  * drmm_simple_encoder_alloc - Allocate and initialize an encoder with basic
0250  *                             functionality.
0251  * @dev: drm device
0252  * @type: the type of the struct which contains struct &drm_encoder
0253  * @member: the name of the &drm_encoder within @type.
0254  * @encoder_type: user visible type of the encoder
0255  *
0256  * Allocates and initializes an encoder that has no further functionality.
0257  * Settings for possible CRTC and clones are left to their initial values.
0258  * Cleanup is automatically handled through registering drm_encoder_cleanup()
0259  * with drmm_add_action().
0260  *
0261  * Returns:
0262  * Pointer to new encoder, or ERR_PTR on failure.
0263  */
0264 #define drmm_simple_encoder_alloc(dev, type, member, encoder_type) \
0265     ((type *)__drmm_simple_encoder_alloc(dev, sizeof(type), \
0266                          offsetof(type, member), \
0267                          encoder_type))
0268
0269 #endif /* __LINUX_DRM_SIMPLE_KMS_HELPER_H */