[4/4] drm/doc: add new dp helpers into drm DocBook

Commit Message

Daniel Vetter Oct. 31, 2012, 9:11 a.m. UTC

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.

Signed-off-by: Daniel Vetter <[e-mail]>
---
 Documentation/DocBook/drm.tmpl  |  6 ++++++
 drivers/gpu/drm/drm_dp_helper.c | 20 ++++++++++++++++++++
 include/drm/drm_dp_helper.h     |  7 +++++++
 3 files changed, 33 insertions(+)

Comments

Laurent Pinchart Nov. 1, 2012, 12:02 p.m. UTC | #1

Hi Daniel,

Thanks for the patch.

On Wednesday 31 October 2012 10:11:50 Daniel Vetter wrote:
> 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.
> 
> Signed-off-by: Daniel Vetter <[e-mail]>
> ---
>  Documentation/DocBook/drm.tmpl  |  6 ++++++
>  drivers/gpu/drm/drm_dp_helper.c | 20 ++++++++++++++++++++
>  include/drm/drm_dp_helper.h     |  7 +++++++
>  3 files changed, 33 insertions(+)
> 
> diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
> index 15729eb..71edb57 100644
> --- a/Documentation/DocBook/drm.tmpl
> +++ b/Documentation/DocBook/drm.tmpl
> @@ -2115,6 +2115,12 @@ void intel_crt_init(struct drm_device *dev)
>  !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 -->
> diff --git a/drivers/gpu/drm/drm_dp_helper.c
> b/drivers/gpu/drm/drm_dp_helper.c index 3c4cccd..2ff6482 100644
> --- a/drivers/gpu/drm/drm_dp_helper.c
> +++ b/drivers/gpu/drm/drm_dp_helper.c
> @@ -30,6 +30,15 @@
>  #include <drm/drm_dp_helper.h>
>  #include <drm/drmP.h>
> 
> +/**
> + * DOC: dp helpers
> + *
> + * These functions contain some come logic and helpers at various

s/come/core/

> + * 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,17 @@ i2c_dp_aux_prepare_bus(struct i2c_adapter *adapter)
>  	return 0;
>  }
> 
> +/**
> + * i2c_dp_aux_add_bus() - register a i2c adaptar using the aux ch helper

s/a i2c adaptar/an I2C adapter/

(feel free to drop the caps if preferred)

> + * @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 which will be used by the the i2c over

s/the the/the/

> + * dp aux algo.

s/algo/algorithm/ ?

> + *
> + * RETURNS:
> + * 0 on success, -ERRNO on failure.
> + */
>  int
>  i2c_dp_aux_add_bus(struct i2c_adapter *adapter)
>  {
> diff --git a/include/drm/drm_dp_helper.h b/include/drm/drm_dp_helper.h
> index c09d367..3f94ede 100644
> --- a/include/drm/drm_dp_helper.h
> +++ b/include/drm/drm_dp_helper.h
> @@ -312,6 +312,13 @@
>  #define MODE_I2C_READ	4
>  #define MODE_I2C_STOP	8
> 
> +/**
> + * struct i2c_algo_dp_aux_data - driver interface structure for i2c over dp
> + * aux algo

s/algo/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;

Patch

diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
index 15729eb..71edb57 100644
--- a/Documentation/DocBook/drm.tmpl
+++ b/Documentation/DocBook/drm.tmpl
@@ -2115,6 +2115,12 @@  void intel_crt_init(struct drm_device *dev)
 !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 -->
diff --git a/drivers/gpu/drm/drm_dp_helper.c b/drivers/gpu/drm/drm_dp_helper.c
index 3c4cccd..2ff6482 100644
--- a/drivers/gpu/drm/drm_dp_helper.c
+++ b/drivers/gpu/drm/drm_dp_helper.c
@@ -30,6 +30,15 @@ 
 #include <drm/drm_dp_helper.h>
 #include <drm/drmP.h>
 
+/**
+ * DOC: dp helpers
+ *
+ * These functions contain some come 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,17 @@  i2c_dp_aux_prepare_bus(struct i2c_adapter *adapter)
 	return 0;
 }
 
+/**
+ * i2c_dp_aux_add_bus() - register a i2c adaptar 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
+ * which will be used by the the i2c over dp aux algo.
+ *
+ * RETURNS:
+ * 0 on success, -ERRNO on failure.
+ */
 int
 i2c_dp_aux_add_bus(struct i2c_adapter *adapter)
 {
diff --git a/include/drm/drm_dp_helper.h b/include/drm/drm_dp_helper.h
index c09d367..3f94ede 100644
--- a/include/drm/drm_dp_helper.h
+++ b/include/drm/drm_dp_helper.h
@@ -312,6 +312,13 @@ 
 #define MODE_I2C_READ	4
 #define MODE_I2C_STOP	8
 
+/**
+ * struct i2c_algo_dp_aux_data - driver interface structure for i2c over dp aux algo
+ * @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;