diff options
Diffstat (limited to 'include/drm/drm_crtc.h')
| -rw-r--r-- | include/drm/drm_crtc.h | 261 |
1 files changed, 186 insertions, 75 deletions
diff --git a/include/drm/drm_crtc.h b/include/drm/drm_crtc.h index 946672f97e1e..629a5fe075b3 100644 --- a/include/drm/drm_crtc.h +++ b/include/drm/drm_crtc.h @@ -39,7 +39,6 @@ #include <drm/drm_framebuffer.h> #include <drm/drm_modes.h> #include <drm/drm_connector.h> -#include <drm/drm_encoder.h> #include <drm/drm_property.h> #include <drm/drm_bridge.h> #include <drm/drm_edid.h> @@ -68,14 +67,12 @@ static inline uint64_t I642U64(int64_t val) } struct drm_crtc; -struct drm_encoder; struct drm_pending_vblank_event; struct drm_plane; struct drm_bridge; struct drm_atomic_state; struct drm_crtc_helper_funcs; -struct drm_encoder_helper_funcs; struct drm_plane_helper_funcs; /** @@ -84,8 +81,8 @@ struct drm_plane_helper_funcs; * @enable: whether the CRTC should be enabled, gates all other state * @active: whether the CRTC is actively displaying (used for DPMS) * @planes_changed: planes on this crtc are updated - * @mode_changed: crtc_state->mode or crtc_state->enable has been changed - * @active_changed: crtc_state->active has been toggled. + * @mode_changed: @mode or @enable has been changed + * @active_changed: @active has been toggled. * @connectors_changed: connectors to this crtc have been updated * @zpos_changed: zpos values of planes on this crtc have been updated * @color_mgmt_changed: color management properties have changed (degamma or @@ -93,23 +90,15 @@ struct drm_plane_helper_funcs; * @plane_mask: bitmask of (1 << drm_plane_index(plane)) of attached planes * @connector_mask: bitmask of (1 << drm_connector_index(connector)) of attached connectors * @encoder_mask: bitmask of (1 << drm_encoder_index(encoder)) of attached encoders - * @last_vblank_count: for helpers and drivers to capture the vblank of the - * update to ensure framebuffer cleanup isn't done too early - * @adjusted_mode: for use by helpers and drivers to compute adjusted mode timings - * @mode: current mode timings * @mode_blob: &drm_property_blob for @mode - * @degamma_lut: Lookup table for converting framebuffer pixel data - * before apply the conversion matrix - * @ctm: Transformation matrix - * @gamma_lut: Lookup table for converting pixel data after the - * conversion matrix * @state: backpointer to global drm_atomic_state * * Note that the distinction between @enable and @active is rather subtile: * Flipping @active while @enable is set without changing anything else may - * never return in a failure from the ->atomic_check callback. Userspace assumes - * that a DPMS On will always succeed. In other words: @enable controls resource - * assignment, @active controls the actual hardware state. + * never return in a failure from the &drm_mode_config_funcs.atomic_check + * callback. Userspace assumes that a DPMS On will always succeed. In other + * words: @enable controls resource assignment, @active controls the actual + * hardware state. * * The three booleans active_changed, connectors_changed and mode_changed are * intended to indicate whether a full modeset is needed, rather than strictly @@ -140,23 +129,81 @@ struct drm_crtc_state { u32 connector_mask; u32 encoder_mask; - /* last_vblank_count: for vblank waits before cleanup */ - u32 last_vblank_count; - - /* adjusted_mode: for use by helpers and drivers */ + /** + * @adjusted_mode: + * + * Internal display timings which can be used by the driver to handle + * differences between the mode requested by userspace in @mode and what + * is actually programmed into the hardware. It is purely driver + * implementation defined what exactly this adjusted mode means. Usually + * it is used to store the hardware display timings used between the + * CRTC and encoder blocks. + */ struct drm_display_mode adjusted_mode; + /** + * @mode: + * + * Display timings requested by userspace. The driver should try to + * match the refresh rate as close as possible (but note that it's + * undefined what exactly is close enough, e.g. some of the HDMI modes + * only differ in less than 1% of the refresh rate). The active width + * and height as observed by userspace for positioning planes must match + * exactly. + * + * For external connectors where the sink isn't fixed (like with a + * built-in panel), this mode here should match the physical mode on the + * wire to the last details (i.e. including sync polarities and + * everything). + */ struct drm_display_mode mode; /* blob property to expose current mode to atomic userspace */ struct drm_property_blob *mode_blob; - /* blob property to expose color management to userspace */ + /** + * @degamma_lut: + * + * Lookup table for converting framebuffer pixel data before apply the + * color conversion matrix @ctm. See drm_crtc_enable_color_mgmt(). The + * blob (if not NULL) is an array of &struct drm_color_lut. + */ struct drm_property_blob *degamma_lut; + + /** + * @ctm: + * + * Color transformation matrix. See drm_crtc_enable_color_mgmt(). The + * blob (if not NULL) is a &struct drm_color_ctm. + */ struct drm_property_blob *ctm; + + /** + * @gamma_lut: + * + * Lookup table for converting pixel data after the color conversion + * matrix @ctm. See drm_crtc_enable_color_mgmt(). The blob (if not + * NULL) is an array of &struct drm_color_lut. + */ struct drm_property_blob *gamma_lut; /** + * @target_vblank: + * + * Target vertical blank period when a page flip + * should take effect. + */ + u32 target_vblank; + + /** + * @pageflip_flags: + * + * DRM_MODE_PAGE_FLIP_* flags, as passed to the page flip ioctl. + * Zero in any other case. + */ + u32 pageflip_flags; + + /** * @event: * * Optional pointer to a DRM event to signal upon completion of the @@ -167,7 +214,9 @@ struct drm_crtc_state { * atomic commit. In that case the event can be send out any time * after the hardware has stopped scanning out the current * framebuffers. It should contain the timestamp and counter for the - * last vblank before the display pipeline was shut off. + * last vblank before the display pipeline was shut off. The simplest + * way to achieve that is calling drm_crtc_send_vblank_event() + * somewhen after drm_crtc_vblank_off() has been called. * * - For a CRTC which is enabled at the end of the commit (even when it * undergoes an full modeset) the vblank timestamp and counter must @@ -195,6 +244,12 @@ struct drm_crtc_state { * drm_crtc_arm_vblank_event(). See the documentation of that function * for a detailed discussion of the constraints it needs to be used * safely. + * + * If the device can't notify of flip completion in a race-free way + * at all, then the event should be armed just after the page flip is + * committed. In the worst case the driver will send the event to + * userspace one frame too late. This doesn't allow for a real atomic + * update, but it should avoid tearing. */ struct drm_pending_vblank_event *event; @@ -298,6 +353,12 @@ struct drm_crtc_funcs { * * This callback is optional. * + * Atomic drivers who want to support gamma tables should implement the + * atomic color management support, enabled by calling + * drm_crtc_enable_color_mgmt(), which then supports the legacy gamma + * interface through the drm_atomic_helper_legacy_gamma_set() + * compatibility implementation. + * * NOTE: * * Drivers that support gamma tables and also fbdev emulation through @@ -307,7 +368,8 @@ struct drm_crtc_funcs { * hooks. */ int (*gamma_set)(struct drm_crtc *crtc, u16 *r, u16 *g, u16 *b, - uint32_t size); + uint32_t size, + struct drm_modeset_acquire_ctx *ctx); /** * @destroy: @@ -323,7 +385,7 @@ struct drm_crtc_funcs { * * This is the main legacy entry point to change the modeset state on a * CRTC. All the details of the desired configuration are passed in a - * struct &drm_mode_set - see there for details. + * &struct drm_mode_set - see there for details. * * Drivers implementing atomic modeset should use * drm_atomic_helper_set_config() to implement this hook. @@ -332,7 +394,8 @@ struct drm_crtc_funcs { * * 0 on success or a negative error code on failure. */ - int (*set_config)(struct drm_mode_set *set); + int (*set_config)(struct drm_mode_set *set, + struct drm_modeset_acquire_ctx *ctx); /** * @page_flip: @@ -345,8 +408,8 @@ struct drm_crtc_funcs { * through the DRM_MODE_PAGE_FLIP_ASYNC flag). When an application * requests a page flip the DRM core verifies that the new frame buffer * is large enough to be scanned out by the CRTC in the currently - * configured mode and then calls the CRTC ->page_flip() operation with a - * pointer to the new frame buffer. + * configured mode and then calls this hook with a pointer to the new + * frame buffer. * * The driver must wait for any pending rendering to the new framebuffer * to complete before executing the flip. It should also wait for any @@ -354,7 +417,7 @@ struct drm_crtc_funcs { * shared dma-buf. * * An application can request to be notified when the page flip has - * completed. The drm core will supply a struct &drm_event in the event + * completed. The drm core will supply a &struct drm_event in the event * parameter in this case. This can be handled by the * drm_crtc_send_vblank_event() function, which the driver should call on * the provided event upon completion of the flip. Note that if @@ -381,7 +444,7 @@ struct drm_crtc_funcs { * RETURNS: * * 0 on success or a negative error code on failure. Note that if a - * ->page_flip() operation is already pending the callback should return + * page flip operation is already pending the callback should return * -EBUSY. Pageflips on a disabled CRTC (either by setting a NULL mode * or just runtime disabled through DPMS respectively the new atomic * "ACTIVE" state) should result in an -EINVAL error code. Note that @@ -390,7 +453,8 @@ struct drm_crtc_funcs { int (*page_flip)(struct drm_crtc *crtc, struct drm_framebuffer *fb, struct drm_pending_vblank_event *event, - uint32_t flags); + uint32_t flags, + struct drm_modeset_acquire_ctx *ctx); /** * @page_flip_target: @@ -408,7 +472,8 @@ struct drm_crtc_funcs { int (*page_flip_target)(struct drm_crtc *crtc, struct drm_framebuffer *fb, struct drm_pending_vblank_event *event, - uint32_t flags, uint32_t target); + uint32_t flags, uint32_t target, + struct drm_modeset_acquire_ctx *ctx); /** * @set_property: @@ -433,19 +498,19 @@ struct drm_crtc_funcs { * @atomic_duplicate_state: * * Duplicate the current atomic state for this CRTC and return it. - * The core and helpers gurantee that any atomic state duplicated with + * The core and helpers guarantee that any atomic state duplicated with * this hook and still owned by the caller (i.e. not transferred to the - * driver by calling ->atomic_commit() from struct - * &drm_mode_config_funcs) will be cleaned up by calling the - * @atomic_destroy_state hook in this structure. + * driver by calling &drm_mode_config_funcs.atomic_commit) will be + * cleaned up by calling the @atomic_destroy_state hook in this + * structure. * - * Atomic drivers which don't subclass struct &drm_crtc should use + * Atomic drivers which don't subclass &struct drm_crtc_state should use * drm_atomic_helper_crtc_duplicate_state(). Drivers that subclass the * state structure to extend it with driver-private state should use * __drm_atomic_helper_crtc_duplicate_state() to make sure shared state is * duplicated in a consistent fashion across drivers. * - * It is an error to call this hook before crtc->state has been + * It is an error to call this hook before &drm_crtc.state has been * initialized correctly. * * NOTE: @@ -558,7 +623,7 @@ struct drm_crtc_funcs { * * This optional hook should be used to unregister the additional * userspace interfaces attached to the crtc from - * late_unregister(). It is called from drm_dev_unregister(), + * @late_register. It is called from drm_dev_unregister(), * early in the driver unload sequence to disable userspace access * before data structures are torndown. */ @@ -575,9 +640,12 @@ struct drm_crtc_funcs { * When CRC generation is enabled, the driver should call * drm_crtc_add_crc_entry() at each frame, providing any information * that characterizes the frame contents in the crcN arguments, as - * provided from the configured source. Drivers must accept a "auto" + * provided from the configured source. Drivers must accept an "auto" * source name that will select a default source for this CRTC. * + * Note that "auto" can depend upon the current modeset configuration, + * e.g. it could pick an encoder or output specific CRC sampling point. + * * This callback is optional if the driver does not support any CRC * generation functionality. * @@ -591,7 +659,7 @@ struct drm_crtc_funcs { /** * @atomic_print_state: * - * If driver subclasses struct &drm_crtc_state, it should implement + * If driver subclasses &struct drm_crtc_state, it should implement * this optional hook for printing additional driver specific state. * * Do not call this directly, use drm_atomic_crtc_print_state() @@ -599,6 +667,50 @@ struct drm_crtc_funcs { */ void (*atomic_print_state)(struct drm_printer *p, const struct drm_crtc_state *state); + + /** + * @get_vblank_counter: + * + * Driver callback for fetching a raw hardware vblank counter for the + * CRTC. It's meant to be used by new drivers as the replacement of + * &drm_driver.get_vblank_counter hook. + * + * This callback is optional. If a device doesn't have a hardware + * counter, the driver can simply leave the hook as NULL. The DRM core + * will account for missed vblank events while interrupts where disabled + * based on system timestamps. + * + * Wraparound handling and loss of events due to modesetting is dealt + * with in the DRM core code, as long as drivers call + * drm_crtc_vblank_off() and drm_crtc_vblank_on() when disabling or + * enabling a CRTC. + * + * Returns: + * + * Raw vblank counter value. + */ + u32 (*get_vblank_counter)(struct drm_crtc *crtc); + + /** + * @enable_vblank: + * + * Enable vblank interrupts for the CRTC. It's meant to be used by + * new drivers as the replacement of &drm_driver.enable_vblank hook. + * + * Returns: + * + * Zero on success, appropriate errno if the vblank interrupt cannot + * be enabled. + */ + int (*enable_vblank)(struct drm_crtc *crtc); + + /** + * @disable_vblank: + * + * Disable vblank interrupts for the CRTC. It's meant to be used by + * new drivers as the replacement of &drm_driver.disable_vblank hook. + */ + void (*disable_vblank)(struct drm_crtc *crtc); }; /** @@ -637,10 +749,12 @@ struct drm_crtc { /** * @mutex: * - * This provides a read lock for the overall crtc state (mode, dpms + * This provides a read lock for the overall CRTC state (mode, dpms * state, ...) and a write lock for everything which can be update - * without a full modeset (fb, cursor data, crtc properties ...). Full - * modeset also need to grab dev->mode_config.connection_mutex. + * without a full modeset (fb, cursor data, CRTC properties ...). A full + * modeset also need to grab &drm_mode_config.connection_mutex. + * + * For atomic drivers specifically this protects @state. */ struct drm_modeset_lock mutex; @@ -686,6 +800,14 @@ struct drm_crtc { * @state: * * Current atomic state for this CRTC. + * + * This is protected by @mutex. Note that nonblocking atomic commits + * access the current CRTC state without taking locks. Either by going + * through the &struct drm_atomic_state pointers, see + * for_each_crtc_in_state(), for_each_oldnew_crtc_in_state(), + * for_each_old_crtc_in_state() and for_each_new_crtc_in_state(). Or + * through careful ordering of atomic commit operations as implemented + * in the atomic helpers, see &struct drm_crtc_commit. */ struct drm_crtc_state *state; @@ -707,15 +829,6 @@ struct drm_crtc { */ spinlock_t commit_lock; - /** - * @acquire_ctx: - * - * Per-CRTC implicit acquire context used by atomic drivers for legacy - * IOCTLs, so that atomic drivers can get at the locking acquire - * context. - */ - struct drm_modeset_acquire_ctx *acquire_ctx; - #ifdef CONFIG_DEBUG_FS /** * @debugfs_entry: @@ -723,6 +836,7 @@ struct drm_crtc { * Debugfs directory for this CRTC. */ struct dentry *debugfs_entry; +#endif /** * @crc: @@ -730,7 +844,6 @@ struct drm_crtc { * Configuration settings of CRC capture. */ struct drm_crtc_crc crc; -#endif /** * @fence_context: @@ -772,10 +885,8 @@ struct drm_crtc { * @connectors: array of connectors to drive with this CRTC if possible * @num_connectors: size of @connectors array * - * Represents a single crtc the connectors that it drives with what mode - * and from which framebuffer it scans out from. - * - * This is used to set modes. + * This represents a modeset configuration for the legacy SETCRTC ioctl and is + * also used internally. Atomic drivers instead use &drm_atomic_state. */ struct drm_mode_set { struct drm_framebuffer *fb; @@ -824,14 +935,21 @@ static inline uint32_t drm_crtc_mask(const struct drm_crtc *crtc) return 1 << drm_crtc_index(crtc); } -void drm_crtc_get_hv_timing(const struct drm_display_mode *mode, - int *hdisplay, int *vdisplay); int drm_crtc_force_disable(struct drm_crtc *crtc); int drm_crtc_force_disable_all(struct drm_device *dev); int drm_mode_set_config_internal(struct drm_mode_set *set); +struct drm_crtc *drm_crtc_from_index(struct drm_device *dev, int idx); -/* Helpers */ +/** + * drm_crtc_find - look up a CRTC object from its ID + * @dev: DRM device + * @id: &drm_mode_object ID + * + * This can be used to look up a CRTC from its userspace ID. Only used by + * drivers for legacy IOCTLs and interface, nowadays extensions to the KMS + * userspace interface should be done using &drm_property. + */ static inline struct drm_crtc *drm_crtc_find(struct drm_device *dev, uint32_t id) { @@ -840,21 +958,14 @@ static inline struct drm_crtc *drm_crtc_find(struct drm_device *dev, return mo ? obj_to_crtc(mo) : NULL; } +/** + * drm_for_each_crtc - iterate over all CRTCs + * @crtc: a &struct drm_crtc as the loop cursor + * @dev: the &struct drm_device + * + * Iterate over all CRTCs of @dev. + */ #define drm_for_each_crtc(crtc, dev) \ list_for_each_entry(crtc, &(dev)->mode_config.crtc_list, head) -static inline void -assert_drm_connector_list_read_locked(struct drm_mode_config *mode_config) -{ - /* - * The connector hotadd/remove code currently grabs both locks when - * updating lists. Hence readers need only hold either of them to be - * safe and the check amounts to - * - * WARN_ON(not_holding(A) && not_holding(B)). - */ - WARN_ON(!mutex_is_locked(&mode_config->mutex) && - !drm_modeset_is_locked(&mode_config->connection_mutex)); -} - #endif /* __DRM_CRTC_H__ */ |