[PATCH v2 1/3] drm/dp_helper: Rework the drm_dp_aux documentation

[Daniel Vetter]

On Wed, Jun 16, 2021 at 04:15:27PM +0200, Maxime Ripard wrote:
> Split the existing documentation to move the comments on particular
> fields next to them.
> 
> Suggested-by: Daniel Vetter <daniel.vetter at ffwll.ch>
> Signed-off-by: Maxime Ripard <maxime at cerno.tech>
> 
> ---
> 
> Changes from v1:
>   - New patch

On the series:

Acked-by: Daniel Vetter <daniel.vetter at ffwll.ch>

Thanks for doing this polish&doc improvement.
-Daniel
> ---
>  include/drm/drm_dp_helper.h | 84 +++++++++++++++++++++++++------------
>  1 file changed, 57 insertions(+), 27 deletions(-)
> 
> diff --git a/include/drm/drm_dp_helper.h b/include/drm/drm_dp_helper.h
> index 1e85c2021f2f..1c5ae07ff0c7 100644
> --- a/include/drm/drm_dp_helper.h
> +++ b/include/drm/drm_dp_helper.h
> @@ -1837,29 +1837,6 @@ struct drm_dp_aux_cec {
>  
>  /**
>   * struct drm_dp_aux - DisplayPort AUX channel
> - * @name: user-visible name of this AUX channel and the I2C-over-AUX adapter
> - * @ddc: I2C adapter that can be used for I2C-over-AUX communication
> - * @dev: pointer to struct device that is the parent for this AUX channel
> - * @crtc: backpointer to the crtc that is currently using this AUX channel
> - * @hw_mutex: internal mutex used for locking transfers
> - * @crc_work: worker that captures CRCs for each frame
> - * @crc_count: counter of captured frame CRCs
> - * @transfer: transfers a message representing a single AUX transaction
> - *
> - * The @dev field should be set to a pointer to the device that implements the
> - * AUX channel.
> - *
> - * The @name field may be used to specify the name of the I2C adapter. If set to
> - * %NULL, dev_name() of @dev will be used.
> - *
> - * Drivers provide a hardware-specific implementation of how transactions are
> - * executed via the @transfer() function. A pointer to a &drm_dp_aux_msg
> - * structure describing the transaction is passed into this function. Upon
> - * success, the implementation should return the number of payload bytes that
> - * were transferred, or a negative error-code on failure. Helpers propagate
> - * errors from the @transfer() function, with the exception of the %-EBUSY
> - * error, which causes a transaction to be retried. On a short, helpers will
> - * return %-EPROTO to make it simpler to check for failure.
>   *
>   * An AUX channel can also be used to transport I2C messages to a sink. A
>   * typical application of that is to access an EDID that's present in the sink
> @@ -1870,21 +1847,74 @@ struct drm_dp_aux_cec {
>   * transfers by default; if a partial response is received, the adapter will
>   * drop down to the size given by the partial response for this transaction
>   * only.
> - *
> - * Note that the aux helper code assumes that the @transfer() function only
> - * modifies the reply field of the &drm_dp_aux_msg structure. The retry logic
> - * and i2c helpers assume this is the case.
>   */
>  struct drm_dp_aux {
> +	/**
> +	 * @name: user-visible name of this AUX channel and the
> +	 * I2C-over-AUX adapter.
> +	 *
> +	 * It's also used to specify the name of the I2C adapter. If set
> +	 * to %NULL, dev_name() of @dev will be used.
> +	 */
>  	const char *name;
> +
> +	/**
> +	 * @ddc: I2C adapter that can be used for I2C-over-AUX
> +	 * communication
> +	 */
>  	struct i2c_adapter ddc;
> +
> +	/**
> +	 * @dev: pointer to struct device that is the parent for this
> +	 * AUX channel.
> +	 */
>  	struct device *dev;
> +
> +	/**
> +	 * @crtc: backpointer to the crtc that is currently using this
> +	 * AUX channel
> +	 */
>  	struct drm_crtc *crtc;
> +
> +	/**
> +	 * @hw_mutex: internal mutex used for locking transfers.
> +	 */
>  	struct mutex hw_mutex;
> +
> +	/**
> +	 * @crc_work: worker that captures CRCs for each frame
> +	 */
>  	struct work_struct crc_work;
> +
> +	/**
> +	 * @crc_count: counter of captured frame CRCs
> +	 */
>  	u8 crc_count;
> +
> +	/**
> +	 * @transfer: transfers a message representing a single AUX
> +	 * transaction.
> +	 *
> +	 * This is a hardware-specific implementation of how
> +	 * transactions are executed that the drivers must provide.
> +	 *
> +	 * A pointer to a &drm_dp_aux_msg structure describing the
> +	 * transaction is passed into this function. Upon success, the
> +	 * implementation should return the number of payload bytes that
> +	 * were transferred, or a negative error-code on failure.
> +	 *
> +	 * Helpers will propagate these errors, with the exception of
> +	 * the %-EBUSY error, which causes a transaction to be retried.
> +	 * On a short, helpers will return %-EPROTO to make it simpler
> +	 * to check for failure.
> +	 *
> +	 * The @transfer() function must only modify the reply field of
> +	 * the &drm_dp_aux_msg structure. The retry logic and i2c
> +	 * helpers assume this is the case.
> +	 */
>  	ssize_t (*transfer)(struct drm_dp_aux *aux,
>  			    struct drm_dp_aux_msg *msg);
> +
>  	/**
>  	 * @i2c_nack_count: Counts I2C NACKs, used for DP validation.
>  	 */
> -- 
> 2.31.1
> 

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch