Document in detail the new refcounted bridges as well as the "legacy"
bridges.
Signed-off-by: Luca Ceresoli <luca.ceresoli@xxxxxxxxxxx>
---
Changes in v6:
- update to the new devm_drm_bridge_alloc() API
- rewrite and improve various sentences for clarity
- fix typos (Randy Dunlap)
This patch was added in v5.
---
Documentation/gpu/drm-kms-helpers.rst | 6 ++
drivers/gpu/drm/drm_bridge.c | 118 ++++++++++++++++++++++++++++++++++
2 files changed, 124 insertions(+)
diff --git a/Documentation/gpu/drm-kms-helpers.rst b/Documentation/gpu/drm-kms-helpers.rst
index 79c8d3e63f7e06136440ed38972697b5f057d5d1..027c6ab65aa5c3848c4afab6fbc8ab93f9a285ba 100644
--- a/Documentation/gpu/drm-kms-helpers.rst
+++ b/Documentation/gpu/drm-kms-helpers.rst
@@ -151,6 +151,12 @@ Overview
.. kernel-doc:: drivers/gpu/drm/drm_bridge.c
:doc: overview
+Bridge lifecycle
+----------------
+
+.. kernel-doc:: drivers/gpu/drm/drm_bridge.c
+ :doc: bridge lifecycle
+
Display Driver Integration
--------------------------
diff --git a/drivers/gpu/drm/drm_bridge.c b/drivers/gpu/drm/drm_bridge.c
index 92ce40adfaa59a278a972ac862bebee06970ff83..fc44a5d227a89a12b5c3299a29776cfddb36ce27 100644
--- a/drivers/gpu/drm/drm_bridge.c
+++ b/drivers/gpu/drm/drm_bridge.c
@@ -62,6 +62,124 @@
* encoder chain.
*/
+/**
+ * DOC: bridge lifecycle
+ *
+ * Allocation, initialization and teardown of a bridge can be implemented
+ * in one of two ways: *refcounted* mode and *legacy* mode.
+ *
+ * In **refcounted** mode:
+ *
+ * - each &struct drm_bridge is reference counted since its allocation
+ * - any code taking a pointer to a bridge has get and put APIs to refcount
+ * it and so ensure the bridge won't be deallocated while there is still
+ * a reference to it
+ * - the driver implementing the bridge also holds a reference, but the
+ * allocated struct can survive it
+ * - deallocation is done when the last put happens, dropping the refcount
+ * to zero
+ *
+ * A bridge using refcounted mode is called a *refcounted bridge*.
+ *
+ * In **legacy** mode the &struct drm_bridge lifetime is tied to the device
+ * instantiating it: it is allocated on probe and freed on removal. Any
+ * other kernel code holding a pointer to the bridge could incur in
+ * use-after-free in case the bridge is deallocated at runtime.
+ *
+ * Legacy mode used to be the only one until refcounted bridges were
+ * introduced, hence the name. It is still fine in case the bridges are a
+ * fixed part of the pipeline, i.e. if the bridges are removed only when
+ * tearing down the entire card. Refcounted bridges support both that case
+ * and the case of more dynamic hardware with bridges that can be removed
+ * at runtime without tearing down the entire card.
+ *
+ * Usage of refcounted bridges happens in two sides: the bridge *provider*
+ * and the bridge *consumers*. The bridge provider is the driver
+ * implementing the bridge. The bridge consumers are all parts of the
+ * kernel taking a &struct drm_bridge pointer, including other bridges,
+ * encoders and the DRM core.
+ *
+ * For bridge **providers**, in both refcounted and legacy modes the common
+ * and expected pattern is that the bridge driver declares a
+ * driver-specific struct embedding a &struct drm_bridge. E.g.::
+ *
+ * struct my_bridge {
+ * ...
+ * struct drm_bridge bridge;
+ * ...
+ * };
+ *
+ * When using refcounted mode, the driver should allocate and initialize
+ * ``struct my_bridge`` using devm_drm_bridge_alloc(), as in this example::
+ *
+ * static int my_bridge_probe(...)
+ * {
+ * struct device *dev = ...;
+ * struct my_bridge *mybr;
+ *
+ * mybr = devm_drm_bridge_alloc(dev, struct my_bridge, bridge, &my_bridge_funcs);
+ * if (IS_ERR(mybr))
+ * return PTR_ERR(mybr);
+ *
+ * // Get resources, initialize my_bridge members...
+ * drm_bridge_add();
+ * ...
+ * }
+ *
+ * static void my_bridge_remove()
+ * {
+ * struct my_bridge *mybr = ...;
+ *
+ * drm_bridge_remove(&mybr->bridge);
+ * // Free resources
+ * // ... NO kfree here!
+ * }
+ *
+ * In legacy mode, the driver can either use ``devm_`` allocation or
+ * equivalently free ``struct my_bridge`` in their remove function::
+ *
+ * static int my_bridge_probe(...)
+ * {
+ * struct device *dev = ...;
+ * struct my_bridge *mybr;
+ *
+ * mybr = devm_kzalloc(dev, sizeof(*mybr), GFP_KERNEL);
+ * if (!mybr)
+ * return -ENOMEM;
+ *
+ * // Get resources, initialize my_bridge members...
+ * mybr->funcs = &my_bridge_funcs;
+ * drm_bridge_add();
+ * ...
+ * }
+ *
+ * static void my_bridge_remove()
+ * {
+ * struct my_bridge *mybr = ...;
+ *
+ * drm_bridge_remove(&mybr->bridge);
+ * // Free resources
+ * // kfree(mybr) if not using devm_*() for allocation
+ * }
+ *
+ * Bridge **consumers** need to handle the case of a bridge being removed
+ * while they have a pointer to it. As this can happen at any time, such
+ * code can incur in use-after-free. To avoid that, consumers have to call
+ * drm_bridge_get() when taking a pointer and drm_bridge_put() after they
+ * are done using it. This will extend the allocation lifetime of the
+ * bridge struct until the last reference has been put, potentially a long
+ * time after the bridge device has been removed from the kernel.
+ *
+ * Functions that return a pointer to a bridge, such as
+ * of_drm_find_bridge(), internally call drm_bridge_get() on the bridge
+ * they are about to return, so in this case the consumers do not have to
+ * do it.
+ *
+ * Calling drm_bridge_get() and drm_bridge_put() on a bridge that is not
+ * refcounted does nothing, so code using these two APIs will work both on
+ * refcounted bridges and legacy bridges.
+ */
+
/**
* DOC: display driver integration
*
--
2.34.1
