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@xxxxxxxx>
> Signed-off-by: Maxime Ripard <maxime@xxxxxxxxxx>
>
> ---
>
> Changes from v1:
> - New patch
On the series:
Acked-by: Daniel Vetter <daniel.vetter@xxxxxxxx>
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
