[PATCH v2 01/28] drm: Introduce drm_bridge_init()

[Mihail Atanassov]

A simple convenience function to initialize the struct drm_bridge. The
goal is to standardize initialization for any bridge registered with
drm_bridge_add() so that we can later add device links for consumers of
those bridges.

v2:
 - s/WARN_ON(!funcs)/WARN_ON(!funcs || !dev)/ as suggested by Daniel
 - expand on some kerneldoc comments as suggested by Daniel
 - update commit message as suggested by Daniel

Signed-off-by: Mihail Atanassov <mihail.atanassov@xxxxxxx>
---
 drivers/gpu/drm/drm_bridge.c | 34 +++++++++++++++++++++++++++++++++-
 include/drm/drm_bridge.h     | 15 ++++++++++++++-
 2 files changed, 47 insertions(+), 2 deletions(-)

diff --git a/drivers/gpu/drm/drm_bridge.c b/drivers/gpu/drm/drm_bridge.c
index cba537c99e43..50e1c1b46e20 100644
--- a/drivers/gpu/drm/drm_bridge.c
+++ b/drivers/gpu/drm/drm_bridge.c
@@ -64,7 +64,10 @@ static DEFINE_MUTEX(bridge_lock);
 static LIST_HEAD(bridge_list);
 
 /**
- * drm_bridge_add - add the given bridge to the global bridge list
+ * drm_bridge_add - add the given bridge to the global bridge list.
+ *
+ * Drivers should call drm_bridge_init() prior adding it to the list.
+ * Drivers should call drm_bridge_remove() to clean up the bridge list.
  *
  * @bridge: bridge control structure
  */
@@ -89,6 +92,35 @@ void drm_bridge_remove(struct drm_bridge *bridge)
 }
 EXPORT_SYMBOL(drm_bridge_remove);
 
+/**
+ * drm_bridge_init - initialise a drm_bridge structure
+ *
+ * @bridge: bridge control structure
+ * @funcs: control functions
+ * @dev: device associated with this drm_bridge
+ * @timings: timing specification for the bridge; optional (may be NULL)
+ * @driver_private: pointer to the bridge driver internal context (may be NULL)
+ */
+void drm_bridge_init(struct drm_bridge *bridge, struct device *dev,
+		     const struct drm_bridge_funcs *funcs,
+		     const struct drm_bridge_timings *timings,
+		     void *driver_private)
+{
+	WARN_ON(!funcs || !dev);
+
+	bridge->dev = NULL;
+	bridge->encoder = NULL;
+	bridge->next = NULL;
+
+#ifdef CONFIG_OF
+	bridge->of_node = dev->of_node;
+#endif
+	bridge->timings = timings;
+	bridge->funcs = funcs;
+	bridge->driver_private = driver_private;
+}
+EXPORT_SYMBOL(drm_bridge_init);
+
 /**
  * drm_bridge_attach - attach the bridge to an encoder's chain
  *
diff --git a/include/drm/drm_bridge.h b/include/drm/drm_bridge.h
index c0a2286a81e9..949e4f401a53 100644
--- a/include/drm/drm_bridge.h
+++ b/include/drm/drm_bridge.h
@@ -373,7 +373,16 @@ struct drm_bridge_timings {
 };
 
 /**
- * struct drm_bridge - central DRM bridge control structure
+ * struct drm_bridge - central DRM bridge control structure.
+ *
+ * Bridge drivers should call drm_bridge_init() to initialize a bridge
+ * driver, and then register it with drm_bridge_add().
+ *
+ * Users of bridges link a bridge driver into their overall display output
+ * pipeline by calling drm_bridge_attach().
+ *
+ * Modular drivers in OF systems can query the list of registered bridges
+ * with of_drm_find_bridge().
  */
 struct drm_bridge {
 	/** @dev: DRM device this bridge belongs to */
@@ -402,6 +411,10 @@ struct drm_bridge {
 
 void drm_bridge_add(struct drm_bridge *bridge);
 void drm_bridge_remove(struct drm_bridge *bridge);
+void drm_bridge_init(struct drm_bridge *bridge, struct device *dev,
+		     const struct drm_bridge_funcs *funcs,
+		     const struct drm_bridge_timings *timings,
+		     void *driver_private);
 struct drm_bridge *of_drm_find_bridge(struct device_node *np);
 int drm_bridge_attach(struct drm_encoder *encoder, struct drm_bridge *bridge,
 		      struct drm_bridge *previous);
-- 
2.23.0