diff options
Diffstat (limited to 'common/recipes-kernel/linux/linux-yocto-4.19.8/0878-drm-amd-display-Start-documentation-of-DC.patch')
| -rw-r--r-- | common/recipes-kernel/linux/linux-yocto-4.19.8/0878-drm-amd-display-Start-documentation-of-DC.patch | 353 |
1 files changed, 353 insertions, 0 deletions
diff --git a/common/recipes-kernel/linux/linux-yocto-4.19.8/0878-drm-amd-display-Start-documentation-of-DC.patch b/common/recipes-kernel/linux/linux-yocto-4.19.8/0878-drm-amd-display-Start-documentation-of-DC.patch new file mode 100644 index 00000000..080af19d --- /dev/null +++ b/common/recipes-kernel/linux/linux-yocto-4.19.8/0878-drm-amd-display-Start-documentation-of-DC.patch @@ -0,0 +1,353 @@ +From e8abfe42e094ef791c5438e9813f7999a9771355 Mon Sep 17 00:00:00 2001 +From: David Francis <David.Francis@amd.com> +Date: Tue, 9 Oct 2018 09:45:28 -0400 +Subject: [PATCH 0878/2940] drm/amd/display: Start documentation of DC + +[Why] +There are a lot of unintuitive parts of the dm-dc interface. +It would help us if these were documented to provide +a common understanding of what they are supposed to do + +[How] +Most of this documentation is stubs, to be filled out more +thoroughly by the experts + +Not every dm-accessible function and struct is mentioned. +Simple functions like getters, setters, retain, release, +create, destroy can be left unadorned. + +Signed-off-by: David Francis <David.Francis@amd.com> +Reviewed-by: Harry Wentland <Harry.Wentland@amd.com> +Acked-by: Leo Li <sunpeng.li@amd.com> +Signed-off-by: Alex Deucher <alexander.deucher@amd.com> +--- + drivers/gpu/drm/amd/display/dc/core/dc.c | 72 ++++++++++++++++++- + drivers/gpu/drm/amd/display/dc/core/dc_link.c | 21 +++++- + .../gpu/drm/amd/display/dc/core/dc_resource.c | 35 +++++++-- + .../gpu/drm/amd/display/dc/core/dc_stream.c | 2 +- + drivers/gpu/drm/amd/display/dc/dc_link.h | 6 +- + .../gpu/drm/amd/display/dc/inc/core_types.h | 12 +++- + 6 files changed, 135 insertions(+), 13 deletions(-) + +diff --git a/drivers/gpu/drm/amd/display/dc/core/dc.c b/drivers/gpu/drm/amd/display/dc/core/dc.c +index 627ca8990991..2d3fa8e792d8 100644 +--- a/drivers/gpu/drm/amd/display/dc/core/dc.c ++++ b/drivers/gpu/drm/amd/display/dc/core/dc.c +@@ -62,6 +62,55 @@ + + const static char DC_BUILD_ID[] = "production-build"; + ++/** ++ * DOC: Overview ++ * ++ * DC is the OS-agnostic component of the amdgpu DC driver. ++ * ++ * DC maintains and validates a set of structs representing the state of the ++ * driver and writes that state to AMD hardware ++ * ++ * Main DC HW structs: ++ * ++ * struct dc - The central struct. One per driver. Created on driver load, ++ * destroyed on driver unload. ++ * ++ * struct dc_context - One per driver. ++ * Used as a backpointer by most other structs in dc. ++ * ++ * struct dc_link - One per connector (the physical DP, HDMI, miniDP, or eDP ++ * plugpoints). Created on driver load, destroyed on driver unload. ++ * ++ * struct dc_sink - One per display. Created on boot or hotplug. ++ * Destroyed on shutdown or hotunplug. A dc_link can have a local sink ++ * (the display directly attached). It may also have one or more remote ++ * sinks (in the Multi-Stream Transport case) ++ * ++ * struct resource_pool - One per driver. Represents the hw blocks not in the ++ * main pipeline. Not directly accessible by dm. ++ * ++ * Main dc state structs: ++ * ++ * These structs can be created and destroyed as needed. There is a full set of ++ * these structs in dc->current_state representing the currently programmed state. ++ * ++ * struct dc_state - The global DC state to track global state information, ++ * such as bandwidth values. ++ * ++ * struct dc_stream_state - Represents the hw configuration for the pipeline from ++ * a framebuffer to a display. Maps one-to-one with dc_sink. ++ * ++ * struct dc_plane_state - Represents a framebuffer. Each stream has at least one, ++ * and may have more in the Multi-Plane Overlay case. ++ * ++ * struct resource_context - Represents the programmable state of everything in ++ * the resource_pool. Not directly accessible by dm. ++ * ++ * struct pipe_ctx - A member of struct resource_context. Represents the ++ * internal hardware pipeline components. Each dc_plane_state has either ++ * one or two (in the pipe-split case). ++ */ ++ + /******************************************************************************* + * Private functions + ******************************************************************************/ +@@ -240,7 +289,7 @@ bool dc_stream_get_crtc_position(struct dc *dc, + } + + /** +- * dc_stream_configure_crc: Configure CRC capture for the given stream. ++ * dc_stream_configure_crc() - Configure CRC capture for the given stream. + * @dc: DC Object + * @stream: The stream to configure CRC on. + * @enable: Enable CRC if true, disable otherwise. +@@ -292,7 +341,7 @@ bool dc_stream_configure_crc(struct dc *dc, struct dc_stream_state *stream, + } + + /** +- * dc_stream_get_crc: Get CRC values for the given stream. ++ * dc_stream_get_crc() - Get CRC values for the given stream. + * @dc: DC object + * @stream: The DC stream state of the stream to get CRCs from. + * @r_cr, g_y, b_cb: CRC values for the three channels are stored here. +@@ -1329,6 +1378,11 @@ static enum surface_update_type check_update_surfaces_for_stream( + return overall_type; + } + ++/** ++ * dc_check_update_surfaces_for_stream() - Determine update type (fast, med, or full) ++ * ++ * See :c:type:`enum surface_update_type <surface_update_type>` for explanation of update types ++ */ + enum surface_update_type dc_check_update_surfaces_for_stream( + struct dc *dc, + struct dc_surface_update *updates, +@@ -1631,6 +1685,9 @@ enum dc_irq_source dc_interrupt_to_irq_source( + return dal_irq_service_to_irq_source(dc->res_pool->irqs, src_id, ext_id); + } + ++/** ++ * dc_interrupt_set() - Enable/disable an AMD hw interrupt source ++ */ + bool dc_interrupt_set(struct dc *dc, enum dc_irq_source src, bool enable) + { + +@@ -1724,6 +1781,11 @@ static bool link_add_remote_sink_helper(struct dc_link *dc_link, struct dc_sink + return true; + } + ++/** ++ * dc_link_add_remote_sink() - Create a sink and attach it to an existing link ++ * ++ * EDID length is in bytes ++ */ + struct dc_sink *dc_link_add_remote_sink( + struct dc_link *link, + const uint8_t *edid, +@@ -1782,6 +1844,12 @@ struct dc_sink *dc_link_add_remote_sink( + return NULL; + } + ++/** ++ * dc_link_remove_remote_sink() - Remove a remote sink from a dc_link ++ * ++ * Note that this just removes the struct dc_sink - it doesn't ++ * program hardware or alter other members of dc_link ++ */ + void dc_link_remove_remote_sink(struct dc_link *link, struct dc_sink *sink) + { + int i; +diff --git a/drivers/gpu/drm/amd/display/dc/core/dc_link.c b/drivers/gpu/drm/amd/display/dc/core/dc_link.c +index 83c2f757a5fb..9d99cdc14b49 100644 +--- a/drivers/gpu/drm/amd/display/dc/core/dc_link.c ++++ b/drivers/gpu/drm/amd/display/dc/core/dc_link.c +@@ -198,6 +198,13 @@ static bool program_hpd_filter( + return result; + } + ++/** ++ * dc_link_detect_sink() - Determine if there is a sink connected ++ * ++ * @type: Returned connection type ++ * Does not detect downstream devices, such as MST sinks ++ * or display connected through active dongles ++ */ + bool dc_link_detect_sink(struct dc_link *link, enum dc_connection_type *type) + { + uint32_t is_hpd_high = 0; +@@ -324,9 +331,9 @@ static enum signal_type get_basic_signal_type( + return SIGNAL_TYPE_NONE; + } + +-/* +- * @brief +- * Check whether there is a dongle on DP connector ++/** ++ * dc_link_is_dp_sink_present() - Check if there is a native DP ++ * or passive DP-HDMI dongle connected + */ + bool dc_link_is_dp_sink_present(struct dc_link *link) + { +@@ -593,6 +600,14 @@ static bool is_same_edid(struct dc_edid *old_edid, struct dc_edid *new_edid) + return (memcmp(old_edid->raw_edid, new_edid->raw_edid, new_edid->length) == 0); + } + ++/** ++ * dc_link_detect() - Detect if a sink is attached to a given link ++ * ++ * link->local_sink is created or destroyed as needed. ++ * ++ * This does not create remote sinks but will trigger DM ++ * to start MST detection if a branch is detected. ++ */ + bool dc_link_detect(struct dc_link *link, enum dc_detect_reason reason) + { + struct dc_sink_init_data sink_init_data = { 0 }; +diff --git a/drivers/gpu/drm/amd/display/dc/core/dc_resource.c b/drivers/gpu/drm/amd/display/dc/core/dc_resource.c +index f014f2f96d84..c4fde1ad97ba 100644 +--- a/drivers/gpu/drm/amd/display/dc/core/dc_resource.c ++++ b/drivers/gpu/drm/amd/display/dc/core/dc_resource.c +@@ -1447,6 +1447,14 @@ static bool are_stream_backends_same( + return true; + } + ++/** ++ * dc_is_stream_unchanged() - Compare two stream states for equivalence. ++ * ++ * Checks if there a difference between the two states ++ * that would require a mode change. ++ * ++ * Does not compare cursor position or attributes. ++ */ + bool dc_is_stream_unchanged( + struct dc_stream_state *old_stream, struct dc_stream_state *stream) + { +@@ -1457,6 +1465,9 @@ bool dc_is_stream_unchanged( + return true; + } + ++/** ++ * dc_is_stream_scaling_unchanged() - Compare scaling rectangles of two streams. ++ */ + bool dc_is_stream_scaling_unchanged( + struct dc_stream_state *old_stream, struct dc_stream_state *stream) + { +@@ -1616,6 +1627,9 @@ bool resource_is_stream_unchanged( + return false; + } + ++/** ++ * dc_add_stream_to_ctx() - Add a new dc_stream_state to a dc_state. ++ */ + enum dc_status dc_add_stream_to_ctx( + struct dc *dc, + struct dc_state *new_ctx, +@@ -1640,6 +1654,9 @@ enum dc_status dc_add_stream_to_ctx( + return res; + } + ++/** ++ * dc_remove_stream_from_ctx() - Remove a stream from a dc_state. ++ */ + enum dc_status dc_remove_stream_from_ctx( + struct dc *dc, + struct dc_state *new_ctx, +@@ -1860,6 +1877,12 @@ enum dc_status resource_map_pool_resources( + return DC_ERROR_UNEXPECTED; + } + ++/** ++ * dc_resource_state_copy_construct_current() - Creates a new dc_state from existing state ++ * Is a shallow copy. Increments refcounts on existing streams and planes. ++ * @dc: copy out of dc->current_state ++ * @dst_ctx: copy into this ++ */ + void dc_resource_state_copy_construct_current( + const struct dc *dc, + struct dc_state *dst_ctx) +@@ -1875,6 +1898,14 @@ void dc_resource_state_construct( + dst_ctx->dccg = dc->res_pool->clk_mgr; + } + ++/** ++ * dc_validate_global_state() - Determine if HW can support a given state ++ * Checks HW resource availability and bandwidth requirement. ++ * @dc: dc struct for this driver ++ * @new_ctx: state to be validated ++ * ++ * Return: DC_OK if the result can be programmed. Otherwise, an error code. ++ */ + enum dc_status dc_validate_global_state( + struct dc *dc, + struct dc_state *new_ctx) +@@ -2364,10 +2395,6 @@ void dc_resource_state_destruct(struct dc_state *context) + } + } + +-/* +- * Copy src_ctx into dst_ctx and retain all surfaces and streams referenced +- * by the src_ctx +- */ + void dc_resource_state_copy_construct( + const struct dc_state *src_ctx, + struct dc_state *dst_ctx) +diff --git a/drivers/gpu/drm/amd/display/dc/core/dc_stream.c b/drivers/gpu/drm/amd/display/dc/core/dc_stream.c +index 780838a05f44..66e5c4623a49 100644 +--- a/drivers/gpu/drm/amd/display/dc/core/dc_stream.c ++++ b/drivers/gpu/drm/amd/display/dc/core/dc_stream.c +@@ -170,7 +170,7 @@ struct dc_stream_status *dc_stream_get_status( + } + + /** +- * Update the cursor attributes and set cursor surface address ++ * dc_stream_set_cursor_attributes() - Update cursor attributes and set cursor surface address + */ + bool dc_stream_set_cursor_attributes( + struct dc_stream_state *stream, +diff --git a/drivers/gpu/drm/amd/display/dc/dc_link.h b/drivers/gpu/drm/amd/display/dc/dc_link.h +index 8738f27a8708..29f19d57ff7a 100644 +--- a/drivers/gpu/drm/amd/display/dc/dc_link.h ++++ b/drivers/gpu/drm/amd/display/dc/dc_link.h +@@ -128,8 +128,10 @@ struct dc_link { + + const struct dc_link_status *dc_link_get_status(const struct dc_link *dc_link); + +-/* +- * Return an enumerated dc_link. dc_link order is constant and determined at ++/** ++ * dc_get_link_at_index() - Return an enumerated dc_link. ++ * ++ * dc_link order is constant and determined at + * boot time. They cannot be created or destroyed. + * Use dc_get_caps() to get number of links. + */ +diff --git a/drivers/gpu/drm/amd/display/dc/inc/core_types.h b/drivers/gpu/drm/amd/display/dc/inc/core_types.h +index 1baa0b1af5e3..a41444caa78b 100644 +--- a/drivers/gpu/drm/amd/display/dc/inc/core_types.h ++++ b/drivers/gpu/drm/amd/display/dc/inc/core_types.h +@@ -272,6 +272,17 @@ union bw_context { + struct dce_bw_output dce; + }; + ++/** ++ * struct dc_state - The full description of a state requested by a user ++ * ++ * @streams: Stream properties ++ * @stream_status: The planes on a given stream ++ * @res_ctx: Persistent state of resources ++ * @bw: The output from bandwidth and watermark calculations ++ * @pp_display_cfg: PowerPlay clocks and settings ++ * @dcn_bw_vars: non-stack memory to support bandwidth calculations ++ * ++ */ + struct dc_state { + struct dc_stream_state *streams[MAX_PIPES]; + struct dc_stream_status stream_status[MAX_PIPES]; +@@ -279,7 +290,6 @@ struct dc_state { + + struct resource_context res_ctx; + +- /* The output from BW and WM calculations. */ + union bw_context bw; + + /* Note: these are big structures, do *not* put on stack! */ +-- +2.17.1 + |