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