display/dc/dc.h

2  * Copyright 2012-2023 Advanced Micro Devices, Inc.
108 	// for example, 1080p -> 8K is 4.0, or 4000 raw value
116 	// for example, 8K -> 1080p is 0.25, or 250 raw value
128  * DOC: color-management-caps
133  * abstracted HW. DCE 5-12 had almost no important changes, but starting with
140  * struct rom_curve_caps - predefined transfer function caps for degamma and regamma
156  * struct dpp_color_caps - color pipeline capabilities for display pipe and
161  * just plain 256-entry lookup
170  * @dgam_rom_for_yuv: pre-defined degamma LUT for YUV planes
171  * @dgam_rom_caps: pre-definied curve caps for degamma 1D LUT
172  * @ogam_rom_caps: pre-definied curve caps for regamma 1D LUT
192  * struct mpc_color_caps - color pipeline capabilities for multiple pipe and
201  * @ogam_rom_caps: pre-definied curve caps for regamma 1D LUT
213  * struct dc_color_caps - color pipes capabilities for DPP and MPC hw blocks
377  * re-programming however do not affect bandwidth consumption or clock
510 	INGAME_FAMS_SINGLE_DISP_ENABLE, // enable in-game fams
511 	INGAME_FAMS_DISABLE, // disable in-game fams
512 	INGAME_FAMS_MULTI_DISP_ENABLE, //enable in-game fams for multi-display
513 …INGAME_FAMS_MULTI_DISP_CLAMPED_ONLY, //enable in-game fams for multi-display only for clamped RR s…
517  * enum pipe_split_policy - Pipe split strategy supported by DCN
525 	 * pipe in order to bring the best trade-off between performance and
557 	DCN_PWR_STATE_UNKNOWN = -1,
572  * struct dc_clocks - DC pipe clocks
643 		unsigned long long start_tick = dc->debug.bw_val_profile.enable ? \
644 				dm_get_timestamp(dc->ctx) : 0
647 		if (dc->debug.bw_val_profile.enable) \
648 			dc->debug.bw_val_profile.total_count++
651 		if (dc->debug.bw_val_profile.enable) { \
653 				voltage_level_tick = dm_get_timestamp(dc->ctx); \
654 			dc->debug.bw_val_profile.skip_ ## status ## _count++; \
658 		if (dc->debug.bw_val_profile.enable) \
659 			voltage_level_tick = dm_get_timestamp(dc->ctx)
662 		if (dc->debug.bw_val_profile.enable) \
663 			watermark_tick = dm_get_timestamp(dc->ctx)
666 		if (dc->debug.bw_val_profile.enable) { \
667 			end_tick = dm_get_timestamp(dc->ctx); \
668 			dc->debug.bw_val_profile.total_ticks += end_tick - start_tick; \
669 			dc->debug.bw_val_profile.voltage_level_ticks += voltage_level_tick - start_tick; \
671 				dc->debug.bw_val_profile.watermark_ticks += watermark_tick - voltage_level_tick; \
672 				dc->debug.bw_val_profile.rq_dlg_ticks += end_tick - watermark_tick; \
775  * 15-2: reserved
776  * 31-16: timeout in ms
849  * struct dc_debug_options - DC debug struct
960 	/* TODO - remove once tested */
1511 	 * Color Transformations for pre-blend MCM (Shaper, 3DLUT, 1DLUT)
1542  * struct dc_validation_set - Struct to store surface/stream associations for validation
1623  * return - minimum required timing bandwidth in kbps.
1629 /* Link Interfaces */
1631  * A link contains one or more sinks and their connected status.
1632  * The currently active signal type (HDMI, DP-SST, DP-MST) is also reported.
1650 	 * If there is no link and local sink, this variable should be set to
1661 	bool hpd_status; /* HPD status of link without physical HPD pin. */
1664 	/* USB4 DPIA links skip verifying link cap, instead performing the fallback method
1665 	 * for every link training. This is incompatible with DP LL compliance automation,
1666 	 * which expects the same link settings to be used every retry on a link loss.
1667 	 * This flag is used to skip the fallback when link loss occurs during automation.
1695 	/* DIG link encoder ID. Used as index in link encoder resource pool.
1705 	 * Pending allows link HWSS to differentiate PHY vs non-PHY pattern,
1708 	 * calls are not performed atomically (i.e. performing link training),
1709 	 * pending_test_pattern will be invalid or contain a non-PHY test pattern
1735 	 * in the BIOS connector table from those that do. Helps when tracking link
1759 	/* MST record stream using this link */
1798 /* Return instance id of the edp link. Inst 0 is primary edp link. */
1800 		const struct dc_link *link,
1803 /* Return an array of link pointers to edp links. */
1811 /* The function initiates detection handshake over the given link. It first
1812  * determines if there are display connections over the link. If so it initiates
1816  * recommended to call this function as the first link operation upon HPD event
1817  * or power up event. Upon completion, the function will update link structure
1819  * to be reset to off for all currently enabled streams to the link. It is DM's
1822  * @reason - Indicate which event triggers this detection. dc may customize
1824  * return false - if detection is not fully completed. This could happen when
1827  * link->connection_type == dc_connection_mst_branch when returning false).
1828  * return true - detection is completed, link has been fully updated with latest
1831 bool dc_link_detect(struct dc_link *link, enum dc_detect_reason reason);
1835 /* When link connection type is dc_connection_mst_branch, remote sink can be
1836  * added to the link. The interface creates a remote sink and associates it with
1837  * current link. The sink will be retained by link until remove remote sink is
1840  * @dc_link - link the remote sink will be added to.
1841  * @edid - byte array of EDID raw data.
1842  * @len - size of the edid in byte
1843  * @init_data -
1851 /* Remove remote sink from a link with dc_connection_mst_branch connection type.
1852  * @link - link the sink should be removed from
1853  * @sink - sink to be removed.
1856 	struct dc_link *link,
1859 /* Enable HPD interrupt handler for a given link */
1860 void dc_link_enable_hpd(const struct dc_link *link);
1862 /* Disable HPD interrupt handler for a given link */
1863 void dc_link_disable_hpd(const struct dc_link *link);
1865 /* determine if there is a sink connected to the link
1867  * @type - dc_connection_single if connected, dc_connection_none otherwise.
1868  * return - false if an unexpected error occurs, true otherwise.
1875 bool dc_link_detect_connection_type(struct dc_link *link,
1879  * return - true HPD is asserted (HPD high), false otherwise (HPD low)
1882 bool dc_link_get_hpd_state(struct dc_link *link);
1884 /* Getter for cached link status from given link */
1885 const struct dc_link_status *dc_link_get_status(const struct dc_link *link);
1889  * @link - The link the HPD pin is associated with.
1890  * @enable = true - enable hardware HPD filter. HPD event will only queued to irq
1897  * @enable = false - disable hardware HPD filter. HPD event will be queued
1901 void dc_link_enable_hpd_filter(struct dc_link *link, bool enable);
1904  * @link_index - index to a link with ddc in i2c mode
1905  * @cmd - i2c command structure
1906  * return - true if success, false otherwise.
1914  * @link_index - index to a link with ddc in i2c mode
1915  * @cmd - i2c command structure
1916  * return - true if success, false otherwise.
1924  * retries or handle error states. The reply is returned in the payload->reply
1926  * transferred,or -1 on a failure.
1938 bool dc_link_is_hdcp14(struct dc_link *link, enum signal_type signal);
1939 bool dc_link_is_hdcp22(struct dc_link *link, enum signal_type signal);
1943  * TODO - When defer_handling is true the function will have a different purpose.
1948  * true - Downstream port status changed. DM should call DC to do the
1950  * false - no change in Downstream port status. No further action required
1957 void dc_link_dp_handle_automated_test(struct dc_link *link);
1959 /* handle DP Link loss sequence and try to recover RX link loss with best
1962 void dc_link_dp_handle_link_loss(struct dc_link *link);
1965  * return true - hpd rx irq should be handled.
1966  * return false - it is safe to ignore hpd rx irq event
1968 bool dc_link_dp_allow_hpd_rx_irq(const struct dc_link *link);
1970 /* Determine if link loss is indicated with a given hpd_irq_dpcd_data.
1971  * @link - link the hpd irq data associated with
1972  * @hpd_irq_dpcd_data - input hpd irq data
1973  * return - true if hpd irq data indicates a link lost
1975 bool dc_link_check_link_loss_status(struct dc_link *link,
1978 /* Read hpd rx irq data from a given link
1979  * @link - link where the hpd irq data should be read from
1980  * @irq_data - output hpd irq data
1981  * return - DC_OK if hpd irq data is read successfully, otherwise hpd irq data
1985 	struct dc_link *link,
1988 /* The function clears recorded DP RX states in the link. DM should call this
1991  * TODO - in the future we should consider to expand link resume interface to
1995 void dc_link_clear_dprx_states(struct dc_link *link);
1997 /* Destruct the mst topology of the link and reset the allocated payload table
2001 bool dc_link_reset_cur_dp_mst_topology(struct dc_link *link);
2003 /* The function calculates effective DP link bandwidth when a given link is
2004  * using the given link settings.
2006  * return - total effective link bandwidth in kbps.
2009 	const struct dc_link *link,
2012 /* The function takes a snapshot of current link resource allocation state
2014  * @map: a dc link resource snapshot defined internally to dc.
2016  * DM needs to capture a snapshot of current link resource allocation mapping
2019  * Some of the link resource is using first come first serve policy.
2022  * restore link resource to its previous state so user will get consistent
2023  * link capability allocation across reboot.
2028 /* This function restores link resource allocation state from a snapshot
2030  * @map: a dc link resource snapshot defined internally to dc.
2032  * DM needs to call this function after initial link detection on boot and
2033  * before first commit streams to restore link resource allocation state
2036  * Some of the link resource is using first come first serve policy.
2039  * restore link resource to its previous state so user will get consistent
2040  * link capability allocation across reboot.
2046  * interface i.e stream_update->dsc_config
2050 /* translate a raw link rate data to bandwidth in kbps */
2053 /* determine the optimal bandwidth given link and required bw.
2054  * @link - current detected link
2055  * @req_bw - requested bandwidth in kbps
2056  * @link_settings - returned most optimal link settings that can fit the
2058  * return - false if link can't support requested bandwidth, true if link
2061 bool dc_link_decide_edp_link_settings(struct dc_link *link,
2065 /* return the max dp link settings can be driven by the link without considering
2068 bool dc_link_dp_get_max_link_enc_cap(const struct dc_link *link,
2071 /* determine when the link is driving MST mode, what DP link channel coding
2074  * @link -  a link with DP RX connection
2075  * return - if stream is committed to this link with MST signal type, type of
2079 		const struct dc_link *link);
2081 /* get max dp link settings the link can enable with all things considered. (i.e
2084  * @link - a link with DP RX connection
2085  * return - max dp link settings the link can enable.
2088 const struct dc_link_settings *dc_link_get_link_cap(const struct dc_link *link);
2090 /* Get the highest encoding format that the link supports; highest meaning the
2093  * @link - a link with DP RX connection
2094  * return - highest encoding format link supports.
2096 enum dc_link_encoding_format dc_link_get_highest_encoding_format(const struct dc_link *link);
2099  * to a link with dp connector signal type.
2100  * @link - a link with dp connector signal type
2101  * return - true if connected, false otherwise
2103 bool dc_link_is_dp_sink_present(struct dc_link *link);
2105 /* Force DP lane settings update to main-link video signal and notify the change
2107  * tuning purpose. The interface assumes link has already been enabled with DP
2110  * @lt_settings - a container structure with desired hw_lane_settings
2114 				struct dc_link *link);
2116 /* Enable a test pattern in Link or PHY layer in an active link for compliance
2117  * test or debugging purpose. The test pattern will remain until next un-plug.
2119  * @link - active link with DP signal output enabled.
2120  * @test_pattern - desired test pattern to output.
2122  * @test_pattern_color_space - for video test pattern choose a desired color
2124  * @p_link_settings - For PHY pattern choose a desired link settings
2125  * @p_custom_pattern - some test pattern will require a custom input to
2127  * @cust_pattern_size - size of the custom pattern input.
2131 	struct dc_link *link,
2138 /* Force DP link settings to always use a specific value until reboot to a
2139  * specific link. If link has already been enabled, the interface will also
2140  * switch to desired link settings immediately. This is a debug interface to
2145 		struct dc_link *link);
2147 /* Force DP link to customize a specific link training behavior by overriding to
2149  * display specific link training issues or apply some display specific
2150  * workaround in link training.
2152  * @link_settings - if not NULL, force preferred link settings to the link.
2153  * @lt_override - a set of override pointers. If any pointer is none NULL, dc
2154  * will apply this particular override in future link training. If NULL is
2162 		struct dc_link *link,
2165 /* return - true if FEC is supported with connected DP RX, false otherwise */
2166 bool dc_link_is_fec_supported(const struct dc_link *link);
2169  * link enablement.
2170  * return - true if FEC should be enabled, false otherwise.
2172 bool dc_link_should_enable_fec(const struct dc_link *link);
2174 /* determine lttpr mode the current link should be enabled with a specific link
2177 enum lttpr_mode dc_link_decide_lttpr_mode(struct dc_link *link,
2181  * NOTE: this interface doesn't update dp main-link. Calling this function will
2182  * cause DP TX main-link and DP RX power states out of sync. DM has to restore
2185  * @on - true to set DP RX in D0 power state, false to set DP RX in D3 power
2188 void dc_link_dp_receiver_power_ctrl(struct dc_link *link, bool on);
2190 /* Force link to read base dp receiver caps from dpcd 000h - 00Fh and overwrite
2191  * current value read from extended receiver cap from 02200h - 0220Fh.
2193  * field, this interface is a workaround to revert link back to use base caps.
2196 		struct dc_link *link);
2198 void dc_link_edp_panel_backlight_power_on(struct dc_link *link,
2209 /* Set/get nits-based backlight level of an embedded panel (eDP, LVDS). */
2210 bool dc_link_set_backlight_level_nits(struct dc_link *link,
2215 bool dc_link_get_backlight_level_nits(struct dc_link *link,
2221 int dc_link_get_target_backlight_pwm(const struct dc_link *link);
2233  * Communicate with DMUB to allow or disallow Panel Replay on the specified link:
2235  * @link: pointer to the dc_link struct instance
2252 bool dc_link_wait_for_t12(struct dc_link *link);
2255  * return - true if trace is initialized and has valid data. False dp trace
2258 bool dc_dp_trace_is_initialized(struct dc_link *link);
2263 bool dc_dp_trace_is_logged(struct dc_link *link,
2270 void dc_dp_trace_set_is_logged_flag(struct dc_link *link,
2274 /* Obtain driver time stamp for last dp link training end. The time stamp is
2276  * @in_detection - true to get link training end time stamp of last link
2277  * training in detection sequence. false to get link training end time stamp
2278  * of last link training in commit (dpms) sequence
2280 unsigned long long dc_dp_trace_get_lt_end_timestamp(struct dc_link *link,
2283 /* Get how many link training attempts dc has done with latest sequence.
2284  * @in_detection - true to get link training count of last link
2285  * training in detection sequence. false to get link training count of last link
2288 const struct dp_trace_lt_counts *dc_dp_trace_get_lt_counts(struct dc_link *link,
2291 /* Get how many link loss has happened since last link training attempts */
2292 unsigned int dc_dp_trace_get_link_loss_count(struct dc_link *link);
2298  * Send a request from DP-Tx requesting to allocate BW remotely after
2302  * @link: pointer to the dc_link struct instance
2307 void dc_link_set_usb4_req_bw_req(struct dc_link *link, int req_bw);
2313  * @link: pointer to the dc_link struct instance
2319 void dc_link_handle_usb4_bw_alloc_response(struct dc_link *link,
2325  * Unplug => de-allocate bw
2327  * @link: pointer to the dc_link struct instance
2328  * @peak_bw: Peak bw used by the link/sink
2333 		struct dc_link *link, int peak_bw);
2348 /* Sink Interfaces - A sink corresponds to a display output device */
2353 	// 8 byte port ID -> ELD.PortID
2355 	// 128bit GUID in binary formufacturer name -> ELD.ManufacturerName
2357 	// 2 byte product code -> ELD.ProductCode
2402 	struct dc_link *link;  member
2419 	struct dc_link *link;  member
2459 		struct dc_link *link,
2517 /* Get dc link index from dpia port index */