change system file

hc

2024-10-09 244b2c5ca8b14627e4a17755e5922221e121c771

 kernel/include/drm/drm_modeset_helper_vtables.h
..
..
@@ -49,6 +49,8 @@
49
49
  */
50
50
 
51
51
 enum mode_set_atomic;
52
+struct drm_writeback_connector;
53
+struct drm_writeback_job;
52
54
 
53
55
 /**
54
56
  * struct drm_crtc_helper_funcs - helper operations for CRTCs
..
..
@@ -418,6 +420,8 @@
418
420
 	 * Drivers can use the @old_crtc_state input parameter if the operations
419
421
 	 * needed to enable the CRTC don't depend solely on the new state but
420
422
 	 * also on the transition between the old state and the new state.
423
+	 *
424
+	 * This function is optional.
421
425
 	 */
422
426
 	void (*atomic_enable)(struct drm_crtc *crtc,
423
427
 			      struct drm_crtc_state *old_crtc_state);
..
..
@@ -441,9 +445,58 @@
441
445
 	 * parameter @old_crtc_state which could be used to access the old
442
446
 	 * state. Atomic drivers should consider to use this one instead
443
447
 	 * of @disable.
448
+	 *
449
+	 * This function is optional.
444
450
 	 */
445
451
 	void (*atomic_disable)(struct drm_crtc *crtc,
446
452
 			       struct drm_crtc_state *old_crtc_state);
453
+
454
+	/**
455
+	 * @get_scanout_position:
456
+	 *
457
+	 * Called by vblank timestamping code.
458
+	 *
459
+	 * Returns the current display scanout position from a CRTC and an
460
+	 * optional accurate ktime_get() timestamp of when the position was
461
+	 * measured. Note that this is a helper callback which is only used
462
+	 * if a driver uses drm_crtc_vblank_helper_get_vblank_timestamp()
463
+	 * for the @drm_crtc_funcs.get_vblank_timestamp callback.
464
+	 *
465
+	 * Parameters:
466
+	 *
467
+	 * crtc:
468
+	 *     The CRTC.
469
+	 * in_vblank_irq:
470
+	 *     True when called from drm_crtc_handle_vblank(). Some drivers
471
+	 *     need to apply some workarounds for gpu-specific vblank irq
472
+	 *     quirks if the flag is set.
473
+	 * vpos:
474
+	 *     Target location for current vertical scanout position.
475
+	 * hpos:
476
+	 *     Target location for current horizontal scanout position.
477
+	 * stime:
478
+	 *     Target location for timestamp taken immediately before
479
+	 *     scanout position query. Can be NULL to skip timestamp.
480
+	 * etime:
481
+	 *     Target location for timestamp taken immediately after
482
+	 *     scanout position query. Can be NULL to skip timestamp.
483
+	 * mode:
484
+	 *     Current display timings.
485
+	 *
486
+	 * Returns vpos as a positive number while in active scanout area.
487
+	 * Returns vpos as a negative number inside vblank, counting the number
488
+	 * of scanlines to go until end of vblank, e.g., -1 means "one scanline
489
+	 * until start of active scanout / end of vblank."
490
+	 *
491
+	 * Returns:
492
+	 *
493
+	 * True on success, false if a reliable scanout position counter could
494
+	 * not be read out.
495
+	 */
496
+	bool (*get_scanout_position)(struct drm_crtc *crtc,
497
+				     bool in_vblank_irq, int *vpos, int *hpos,
498
+				     ktime_t *stime, ktime_t *etime,
499
+				     const struct drm_display_mode *mode);
447
500
 };
448
501
 
449
502
 /**
..
..
@@ -464,11 +517,6 @@
464
517
  * helpers and the new atomic modesetting helpers.
465
518
  */
466
519
 struct drm_encoder_helper_funcs {
467
-	/**
468
-	 * @loader_protect:
469
-	 * protect loader logo encoder's power.
470
-	 */
471
-	int (*loader_protect)(struct drm_encoder *encoder, bool on);
472
520
 	/**
473
521
 	 * @dpms:
474
522
 	 *
..
..
@@ -645,22 +693,6 @@
645
693
 				struct drm_connector_state *conn_state);
646
694
 
647
695
 	/**
648
-	 * @get_crtc:
649
-	 *
650
-	 * This callback is used by the legacy CRTC helpers to work around
651
-	 * deficiencies in its own book-keeping.
652
-	 *
653
-	 * Do not use, use atomic helpers instead, which get the book keeping
654
-	 * right.
655
-	 *
656
-	 * FIXME:
657
-	 *
658
-	 * Currently only nouveau is using this, and as soon as nouveau is
659
-	 * atomic we can ditch this hook.
660
-	 */
661
-	struct drm_crtc *(*get_crtc)(struct drm_encoder *encoder);
662
-
663
-	/**
664
696
 	 * @detect:
665
697
 	 *
666
698
 	 * This callback can be used by drivers who want to do detection on the
..
..
@@ -679,6 +711,52 @@
679
711
 					    struct drm_connector *connector);
680
712
 
681
713
 	/**
714
+	 * @atomic_disable:
715
+	 *
716
+	 * This callback should be used to disable the encoder. With the atomic
717
+	 * drivers it is called before this encoder's CRTC has been shut off
718
+	 * using their own &drm_crtc_helper_funcs.atomic_disable hook. If that
719
+	 * sequence is too simple drivers can just add their own driver private
720
+	 * encoder hooks and call them from CRTC's callback by looping over all
721
+	 * encoders connected to it using for_each_encoder_on_crtc().
722
+	 *
723
+	 * This callback is a variant of @disable that provides the atomic state
724
+	 * to the driver. If @atomic_disable is implemented, @disable is not
725
+	 * called by the helpers.
726
+	 *
727
+	 * This hook is only used by atomic helpers. Atomic drivers don't need
728
+	 * to implement it if there's no need to disable anything at the encoder
729
+	 * level. To ensure that runtime PM handling (using either DPMS or the
730
+	 * new "ACTIVE" property) works @atomic_disable must be the inverse of
731
+	 * @atomic_enable.
732
+	 */
733
+	void (*atomic_disable)(struct drm_encoder *encoder,
734
+			       struct drm_atomic_state *state);
735
+
736
+	/**
737
+	 * @atomic_enable:
738
+	 *
739
+	 * This callback should be used to enable the encoder. It is called
740
+	 * after this encoder's CRTC has been enabled using their own
741
+	 * &drm_crtc_helper_funcs.atomic_enable hook. If that sequence is
742
+	 * too simple drivers can just add their own driver private encoder
743
+	 * hooks and call them from CRTC's callback by looping over all encoders
744
+	 * connected to it using for_each_encoder_on_crtc().
745
+	 *
746
+	 * This callback is a variant of @enable that provides the atomic state
747
+	 * to the driver. If @atomic_enable is implemented, @enable is not
748
+	 * called by the helpers.
749
+	 *
750
+	 * This hook is only used by atomic helpers, it is the opposite of
751
+	 * @atomic_disable. Atomic drivers don't need to implement it if there's
752
+	 * no need to enable anything at the encoder level. To ensure that
753
+	 * runtime PM handling works @atomic_enable must be the inverse of
754
+	 * @atomic_disable.
755
+	 */
756
+	void (*atomic_enable)(struct drm_encoder *encoder,
757
+			      struct drm_atomic_state *state);
758
+
759
+	/**
682
760
 	 * @disable:
683
761
 	 *
684
762
 	 * This callback should be used to disable the encoder. With the atomic
..
..
@@ -693,6 +771,9 @@
693
771
 	 * disable anything at the encoder level. To ensure that runtime PM
694
772
 	 * handling (using either DPMS or the new "ACTIVE" property) works
695
773
 	 * @disable must be the inverse of @enable for atomic drivers.
774
+	 *
775
+	 * For atomic drivers also consider @atomic_disable and save yourself
776
+	 * from having to read the NOTE below!
696
777
 	 *
697
778
 	 * NOTE:
698
779
 	 *
..
..
@@ -718,11 +799,11 @@
718
799
 	 * hooks and call them from CRTC's callback by looping over all encoders
719
800
 	 * connected to it using for_each_encoder_on_crtc().
720
801
 	 *
721
-	 * This hook is used only by atomic helpers, for symmetry with @disable.
722
-	 * Atomic drivers don't need to implement it if there's no need to
723
-	 * enable anything at the encoder level. To ensure that runtime PM handling
724
-	 * (using either DPMS or the new "ACTIVE" property) works
725
-	 * @enable must be the inverse of @disable for atomic drivers.
802
+	 * This hook is only used by atomic helpers, it is the opposite of
803
+	 * @disable. Atomic drivers don't need to implement it if there's no
804
+	 * need to enable anything at the encoder level. To ensure that
805
+	 * runtime PM handling (using either DPMS or the new "ACTIVE" property)
806
+	 * works @enable must be the inverse of @disable for atomic drivers.
726
807
 	 */
727
808
 	void (*enable)(struct drm_encoder *encoder);
728
809
 
..
..
@@ -785,12 +866,6 @@
785
866
  * probe helpers.
786
867
  */
787
868
 struct drm_connector_helper_funcs {
788
-	/**
789
-	 * @loader_protect:
790
-	 *
791
-	 * protect loader logo connector's power
792
-	 */
793
-	int (*loader_protect)(struct drm_connector *connector, bool on);
794
869
 	/**
795
870
 	 * @get_modes:
796
871
 	 *
..
..
@@ -893,6 +968,48 @@
893
968
 	 */
894
969
 	enum drm_mode_status (*mode_valid)(struct drm_connector *connector,
895
970
 					   struct drm_display_mode *mode);
971
+
972
+	/**
973
+	 * @mode_valid_ctx:
974
+	 *
975
+	 * Callback to validate a mode for a connector, irrespective of the
976
+	 * specific display configuration.
977
+	 *
978
+	 * This callback is used by the probe helpers to filter the mode list
979
+	 * (which is usually derived from the EDID data block from the sink).
980
+	 * See e.g. drm_helper_probe_single_connector_modes().
981
+	 *
982
+	 * This function is optional, and is the atomic version of
983
+	 * &drm_connector_helper_funcs.mode_valid.
984
+	 *
985
+	 * To allow for accessing the atomic state of modesetting objects, the
986
+	 * helper libraries always call this with ctx set to a valid context,
987
+	 * and &drm_mode_config.connection_mutex will always be locked with
988
+	 * the ctx parameter set to @ctx. This allows for taking additional
989
+	 * locks as required.
990
+	 *
991
+	 * Even though additional locks may be acquired, this callback is
992
+	 * still expected not to take any constraints into account which would
993
+	 * be influenced by the currently set display state - such constraints
994
+	 * should be handled in the driver's atomic check. For example, if a
995
+	 * connector shares display bandwidth with other connectors then it
996
+	 * would be ok to validate the minimum bandwidth requirement of a mode
997
+	 * against the maximum possible bandwidth of the connector. But it
998
+	 * wouldn't be ok to take the current bandwidth usage of other
999
+	 * connectors into account, as this would change depending on the
1000
+	 * display state.
1001
+	 *
1002
+	 * Returns:
1003
+	 * 0 if &drm_connector_helper_funcs.mode_valid_ctx succeeded and wrote
1004
+	 * the &enum drm_mode_status value to @status, or a negative error
1005
+	 * code otherwise.
1006
+	 *
1007
+	 */
1008
+	int (*mode_valid_ctx)(struct drm_connector *connector,
1009
+			      struct drm_display_mode *mode,
1010
+			      struct drm_modeset_acquire_ctx *ctx,
1011
+			      enum drm_mode_status *status);
1012
+
896
1013
 	/**
897
1014
 	 * @best_encoder:
898
1015
 	 *
..
..
@@ -911,9 +1028,8 @@
911
1028
 	 * @atomic_best_encoder.
912
1029
 	 *
913
1030
 	 * You can leave this function to NULL if the connector is only
914
-	 * attached to a single encoder and you are using the atomic helpers.
915
-	 * In this case, the core will call drm_atomic_helper_best_encoder()
916
-	 * for you.
1031
+	 * attached to a single encoder. In this case, the core will call
1032
+	 * drm_connector_get_single_encoder() for you.
917
1033
 	 *
918
1034
 	 * RETURNS:
919
1035
 	 *
..
..
@@ -933,7 +1049,7 @@
933
1049
 	 *
934
1050
 	 * This function is used by drm_atomic_helper_check_modeset().
935
1051
 	 * If it is not implemented, the core will fallback to @best_encoder
936
-	 * (or drm_atomic_helper_best_encoder() if @best_encoder is NULL).
1052
+	 * (or drm_connector_get_single_encoder() if @best_encoder is NULL).
937
1053
 	 *
938
1054
 	 * NOTE:
939
1055
 	 *
..
..
@@ -1000,6 +1116,38 @@
1000
1116
 	 */
1001
1117
 	void (*atomic_commit)(struct drm_connector *connector,
1002
1118
 			      struct drm_connector_state *state);
1119
+
1120
+	/**
1121
+	 * @prepare_writeback_job:
1122
+	 *
1123
+	 * As writeback jobs contain a framebuffer, drivers may need to
1124
+	 * prepare and clean them up the same way they can prepare and
1125
+	 * clean up framebuffers for planes. This optional connector operation
1126
+	 * is used to support the preparation of writeback jobs. The job
1127
+	 * prepare operation is called from drm_atomic_helper_prepare_planes()
1128
+	 * for struct &drm_writeback_connector connectors only.
1129
+	 *
1130
+	 * This operation is optional.
1131
+	 *
1132
+	 * This callback is used by the atomic modeset helpers.
1133
+	 */
1134
+	int (*prepare_writeback_job)(struct drm_writeback_connector *connector,
1135
+				     struct drm_writeback_job *job);
1136
+	/**
1137
+	 * @cleanup_writeback_job:
1138
+	 *
1139
+	 * This optional connector operation is used to support the
1140
+	 * cleanup of writeback jobs. The job cleanup operation is called
1141
+	 * from the existing drm_writeback_cleanup_job() function, invoked
1142
+	 * both when destroying the job as part of an aborted commit, or when
1143
+	 * the job completes.
1144
+	 *
1145
+	 * This operation is optional.
1146
+	 *
1147
+	 * This callback is used by the atomic modeset helpers.
1148
+	 */
1149
+	void (*cleanup_writeback_job)(struct drm_writeback_connector *connector,
1150
+				      struct drm_writeback_job *job);
1003
1151
 };
1004
1152
 
1005
1153
 /**
..
..
@@ -1024,7 +1172,7 @@
1024
1172
 	 * @prepare_fb:
1025
1173
 	 *
1026
1174
 	 * This hook is to prepare a framebuffer for scanout by e.g. pinning
1027
-	 * it's backing storage or relocating it into a contiguous block of
1175
+	 * its backing storage or relocating it into a contiguous block of
1028
1176
 	 * VRAM. Other possible preparatory work includes flushing caches.
1029
1177
 	 *
1030
1178
 	 * This function must not block for outstanding rendering, since it is