drm/doc: add new dp helpers into drm DocBook

I didn't bother with documenting the really trivial new "extract something from dpcd" helpers, but the i2c over aux ch is now documented a bit. v2: Clarify the comment for i2c_dp_aux_add_bus a bit. v3: Fix more spelling fail spotted by Laurent Pinchart. Acked-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch> Signed-off-by: Dave Airlie <airlied@redhat.com>

drm/doc: add new dp helpers into drm DocBook
I didn't bother with documenting the really trivial new "extract something from dpcd" helpers, but the i2c over aux ch is now documented a bit. v2: Clarify the comment for i2c_dp_aux_add_bus a bit. v3: Fix more spelling fail spotted by Laurent Pinchart. Acked-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch> Signed-off-by: Dave Airlie <airlied@redhat.com>
Daniel Vetter · Dave Airlie
1 parent d0ddc0338a
Showing 3 changed files with 35 additions and 0 deletions Side-by-side Diff
Documentation/DocBook/drm.tmpl
drivers/gpu/drm/drm_dp_helper.c
include/drm/drm_dp_helper.h
@@ -2105,6 +2105,12 @@
 !Pdrivers/gpu/drm/drm_fb_helper.c fbdev helpers
 !Edrivers/gpu/drm/drm_fb_helper.c
     </sect2>
+    <sect2>
+      <title>Display Port Helper Functions Reference</title>
+!Pdrivers/gpu/drm/drm_dp_helper.c dp helpers
+!Iinclude/drm/drm_dp_helper.h
+!Edrivers/gpu/drm/drm_dp_helper.c
+    </sect2>
   </sect1>
  
   <!-- Internals: vertical blanking -->
@@ -30,6 +30,15 @@
 #include <drm/drm_dp_helper.h>
 #include <drm/drmP.h>
  
+/**
+ * DOC: dp helpers
+ *
+ * These functions contain some common logic and helpers at various abstraction
+ * levels to deal with Display Port sink devices and related things like DP aux
+ * channel transfers, EDID reading over DP aux channels, decoding certain DPCD
+ * blocks, ...
+ */
+
 /* Run a single AUX_CH I2C transaction, writing/reading data as necessary */
 static int
 i2c_algo_dp_aux_transaction(struct i2c_adapter *adapter, int mode,
@@ -193,6 +202,18 @@
 	return 0;
 }
  
+/**
+ * i2c_dp_aux_add_bus() - register an i2c adapter using the aux ch helper
+ * @adapter: i2c adapter to register
+ *
+ * This registers an i2c adapater that uses dp aux channel as it's underlaying
+ * transport. The driver needs to fill out the &i2c_algo_dp_aux_data structure
+ * and store it in the algo_data member of the @adapter argument. This will be
+ * used by the i2c over dp aux algorithm to drive the hardware.
+ *
+ * RETURNS:
+ * 0 on success, -ERRNO on failure.
+ */
 int
 i2c_dp_aux_add_bus(struct i2c_adapter *adapter)
 {
@@ -312,6 +312,14 @@
 #define MODE_I2C_READ	4
 #define MODE_I2C_STOP	8
  
+/**
+ * struct i2c_algo_dp_aux_data - driver interface structure for i2c over dp
+ * 				 aux algorithm
+ * @running: set by the algo indicating whether an i2c is ongoing or whether
+ * 	     the i2c bus is quiescent
+ * @address: i2c target address for the currently ongoing transfer
+ * @aux_ch: driver callback to transfer a single byte of the i2c payload
+ */
 struct i2c_algo_dp_aux_data {
 	bool running;
 	u16 address;
...	...	@@ -2105,6 +2105,12 @@
2105	2105	!Pdrivers/gpu/drm/drm_fb_helper.c fbdev helpers
2106	2106	!Edrivers/gpu/drm/drm_fb_helper.c
2107	2107	</sect2>
	2108	+ <sect2>
	2109	+ <title>Display Port Helper Functions Reference</title>
	2110	+!Pdrivers/gpu/drm/drm_dp_helper.c dp helpers
	2111	+!Iinclude/drm/drm_dp_helper.h
	2112	+!Edrivers/gpu/drm/drm_dp_helper.c
	2113	+ </sect2>
2108	2114	</sect1>
2109	2115
2110	2116	<!-- Internals: vertical blanking -->
...	...	@@ -30,6 +30,15 @@
30	30	#include <drm/drm_dp_helper.h>
31	31	#include <drm/drmP.h>
32	32
	33	+/**
	34	+ * DOC: dp helpers
	35	+ *
	36	+ * These functions contain some common logic and helpers at various abstraction
	37	+ * levels to deal with Display Port sink devices and related things like DP aux
	38	+ * channel transfers, EDID reading over DP aux channels, decoding certain DPCD
	39	+ * blocks, ...
	40	+ */
	41	+
33	42	/* Run a single AUX_CH I2C transaction, writing/reading data as necessary */
34	43	static int
35	44	i2c_algo_dp_aux_transaction(struct i2c_adapter *adapter, int mode,
...	...	@@ -193,6 +202,18 @@
193	202	return 0;
194	203	}
195	204
	205	+/**
	206	+ * i2c_dp_aux_add_bus() - register an i2c adapter using the aux ch helper
	207	+ * @adapter: i2c adapter to register
	208	+ *
	209	+ * This registers an i2c adapater that uses dp aux channel as it's underlaying
	210	+ * transport. The driver needs to fill out the &i2c_algo_dp_aux_data structure
	211	+ * and store it in the algo_data member of the @adapter argument. This will be
	212	+ * used by the i2c over dp aux algorithm to drive the hardware.
	213	+ *
	214	+ * RETURNS:
	215	+ * 0 on success, -ERRNO on failure.
	216	+ */
196	217	int
197	218	i2c_dp_aux_add_bus(struct i2c_adapter *adapter)
198	219	{
...	...	@@ -312,6 +312,14 @@
312	312	#define MODE_I2C_READ 4
313	313	#define MODE_I2C_STOP 8
314	314
	315	+/**
	316	+ * struct i2c_algo_dp_aux_data - driver interface structure for i2c over dp
	317	+ * aux algorithm
	318	+ * @running: set by the algo indicating whether an i2c is ongoing or whether
	319	+ * the i2c bus is quiescent
	320	+ * @address: i2c target address for the currently ongoing transfer
	321	+ * @aux_ch: driver callback to transfer a single byte of the i2c payload
	322	+ */
315	323	struct i2c_algo_dp_aux_data {
316	324	bool running;
317	325	u16 address;