leandrof/linux
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

drm/dp_helper: Rework the drm_dp_aux documentation

Browse Source 
Split the existing documentation to move the comments on particular
fields next to them.

Suggested-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: Maxime Ripard <maxime@cerno.tech>
Acked-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Link: https://patchwork.freedesktop.org/patch/msgid/20210616141529.630719-1-maxime@cerno.tech
This commit is contained in:
Maxime Ripard
2021-06-16 16:15:27 +02:00
parent 5c68ab9276
commit 14407d3afe
1 changed files with 69 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files

102
include/drm/drm_dp_helper.h
View File

@@ -1859,35 +1859,6 @@ struct drm_dp_aux_cec {
/** /**
* struct drm_dp_aux - DisplayPort AUX channel * 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
* @drm_dev: pointer to the &drm_device that owns this AUX channel. Beware, this
* may be %NULL before drm_dp_aux_register() has been called.
* @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. As well, the @drm_dev field should be set to the &drm_device
* that will be using this AUX channel as early as possible. For many graphics
* drivers this should happen before drm_dp_aux_init(), however it's perfectly
* fine to set this field later so long as it's assigned before calling
* drm_dp_aux_register().
*
* 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 * 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 * typical application of that is to access an EDID that's present in the sink
@@ -1898,22 +1869,87 @@ struct drm_dp_aux_cec {
* transfers by default; if a partial response is received, the adapter will * 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 * drop down to the size given by the partial response for this transaction
* only. * 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 { 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; const char *name;
/**
* @ddc: I2C adapter that can be used for I2C-over-AUX
* communication
*/
struct i2c_adapter ddc; struct i2c_adapter ddc;
/**
* @dev: pointer to struct device that is the parent for this
* AUX channel.
*/
struct device *dev; struct device *dev;
/**
* @drm_dev: pointer to the &drm_device that owns this AUX channel.
* Beware, this may be %NULL before drm_dp_aux_register() has been
* called.
*
* It should be set to the &drm_device that will be using this AUX
* channel as early as possible. For many graphics drivers this should
* happen before drm_dp_aux_init(), however it's perfectly fine to set
* this field later so long as it's assigned before calling
* drm_dp_aux_register().
*/
struct drm_device *drm_dev; struct drm_device *drm_dev;
/**
* @crtc: backpointer to the crtc that is currently using this
* AUX channel
*/
struct drm_crtc *crtc; struct drm_crtc *crtc;
/**
* @hw_mutex: internal mutex used for locking transfers.
*/
struct mutex hw_mutex; struct mutex hw_mutex;
/**
* @crc_work: worker that captures CRCs for each frame
*/
struct work_struct crc_work; struct work_struct crc_work;
/**
* @crc_count: counter of captured frame CRCs
*/
u8 crc_count; 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, ssize_t (*transfer)(struct drm_dp_aux *aux,
struct drm_dp_aux_msg *msg); struct drm_dp_aux_msg *msg);
/** /**
* @i2c_nack_count: Counts I2C NACKs, used for DP validation. * @i2c_nack_count: Counts I2C NACKs, used for DP validation.
*/ */