Commit d574528a authored by Daniel Vetter's avatar Daniel Vetter
Browse files

drm/kms-core: Use recommened kerneldoc for struct member refs 



I just learned that &struct_name.member_name works and looks pretty
even. It doesn't (yet) link to the member directly though, which would
be really good for big structures or vfunc tables (where the
per-member kerneldoc tends to be long).

Also some minor drive-by polish where it makes sense, I read a lot
of docs ...

v2: Review from Eric.

Cc: Jani Nikula <jani.nikula@linux.intel.com>
Cc: Chris Wilson <chris@chris-wilson.co.uk>
Reviewed-by: default avatarEric Engestrom <eric.engestrom@imgtec.com>
Signed-off-by: default avatarDaniel Vetter <daniel.vetter@intel.com>
Link: http://patchwork.freedesktop.org/patch/msgid/20170125062657.19270-4-daniel.vetter@ffwll.ch
parent ef40cbf9

drivers/gpu/drm/drm_atomic.c

+37 −41
Original line number Diff line number Diff line
@@ -195,8 +195,8 @@ EXPORT_SYMBOL(drm_atomic_state_default_clear); 
 * all locks. So someone else could sneak in and change the current modeset

 * configuration. Which means that all the state assembled in @state is no

 * longer an atomic update to the current state, but to some arbitrary earlier

 * state. Which could break assumptions the driver's ->atomic_check likely

 * relies on.

 * state. Which could break assumptions the driver's

 * &drm_mode_config_funcs.atomic_check likely relies on.

 *

 * Hence we must clear all cached state and completely start over, using this

 * function.
@@ -456,11 +456,10 @@ drm_atomic_replace_property_blob_from_id(struct drm_crtc *crtc, 
 * @property: the property to set

 * @val: the new property value

 *

 * Use this instead of calling crtc->atomic_set_property directly.

 * This function handles generic/core properties and calls out to

 * driver's ->atomic_set_property() for driver properties.  To ensure

 * consistent behavior you must call this function rather than the

 * driver hook directly.

 * This function handles generic/core properties and calls out to driver's

 * &drm_crtc_funcs.atomic_set_property for driver properties. To ensure

 * consistent behavior you must call this function rather than the driver hook

 * directly.

 *

 * RETURNS:

 * Zero on success, error code on failure
@@ -532,10 +531,10 @@ EXPORT_SYMBOL(drm_atomic_crtc_set_property); 
 * @property: the property to set

 * @val: return location for the property value

 *

 * This function handles generic/core properties and calls out to

 * driver's ->atomic_get_property() for driver properties.  To ensure

 * consistent behavior you must call this function rather than the

 * driver hook directly.

 * This function handles generic/core properties and calls out to driver's

 * &drm_crtc_funcs.atomic_get_property for driver properties. To ensure

 * consistent behavior you must call this function rather than the driver hook

 * directly.

 *

 * RETURNS:

 * Zero on success, error code on failure
@@ -716,11 +715,10 @@ EXPORT_SYMBOL(drm_atomic_get_plane_state); 
 * @property: the property to set

 * @val: the new property value

 *

 * Use this instead of calling plane->atomic_set_property directly.

 * This function handles generic/core properties and calls out to

 * driver's ->atomic_set_property() for driver properties.  To ensure

 * consistent behavior you must call this function rather than the

 * driver hook directly.

 * This function handles generic/core properties and calls out to driver's

 * &drm_plane_funcs.atomic_set_property for driver properties.  To ensure

 * consistent behavior you must call this function rather than the driver hook

 * directly.

 *

 * RETURNS:

 * Zero on success, error code on failure
@@ -791,10 +789,10 @@ EXPORT_SYMBOL(drm_atomic_plane_set_property); 
 * @property: the property to set

 * @val: return location for the property value

 *

 * This function handles generic/core properties and calls out to

 * driver's ->atomic_get_property() for driver properties.  To ensure

 * consistent behavior you must call this function rather than the

 * driver hook directly.

 * This function handles generic/core properties and calls out to driver's

 * &drm_plane_funcs.atomic_get_property for driver properties.  To ensure

 * consistent behavior you must call this function rather than the driver hook

 * directly.

 *

 * RETURNS:

 * Zero on success, error code on failure
@@ -1057,11 +1055,10 @@ EXPORT_SYMBOL(drm_atomic_get_connector_state); 
 * @property: the property to set

 * @val: the new property value

 *

 * Use this instead of calling connector->atomic_set_property directly.

 * This function handles generic/core properties and calls out to

 * driver's ->atomic_set_property() for driver properties.  To ensure

 * consistent behavior you must call this function rather than the

 * driver hook directly.

 * This function handles generic/core properties and calls out to driver's

 * &drm_connector_funcs.atomic_set_property for driver properties.  To ensure

 * consistent behavior you must call this function rather than the driver hook

 * directly.

 *

 * RETURNS:

 * Zero on success, error code on failure
@@ -1136,10 +1133,10 @@ static void drm_atomic_connector_print_state(struct drm_printer *p, 
 * @property: the property to set

 * @val: return location for the property value

 *

 * This function handles generic/core properties and calls out to

 * driver's ->atomic_get_property() for driver properties.  To ensure

 * consistent behavior you must call this function rather than the

 * driver hook directly.

 * This function handles generic/core properties and calls out to driver's

 * &drm_connector_funcs.atomic_get_property for driver properties.  To ensure

 * consistent behavior you must call this function rather than the driver hook

 * directly.

 *

 * RETURNS:

 * Zero on success, error code on failure
@@ -1312,12 +1309,11 @@ EXPORT_SYMBOL(drm_atomic_set_fb_for_plane); 
 * implicit or explicit fencing.

 *

 * This function will not set the fence to the state if it was set

 * via explicit fencing interfaces on the atomic ioctl. It will

 * all drope the reference to the fence as we not storing it

 * anywhere.

 *

 * Otherwise, if plane_state->fence is not set this function we

 * just set it with the received implict fence.

 * via explicit fencing interfaces on the atomic ioctl. In that case it will

 * drop the reference to the fence as we are not storing it anywhere.

 * Otherwise, if &drm_plane_state.fence is not set this function we just set it

 * with the received implicit fence. In both cases this function consumes a

 * reference for @fence.

 */

void

drm_atomic_set_fence_for_plane(struct drm_plane_state *plane_state,
@@ -1616,7 +1612,7 @@ int drm_atomic_commit(struct drm_atomic_state *state) 
EXPORT_SYMBOL(drm_atomic_commit);



/**

 * drm_atomic_nonblocking_commit - atomic&nonblocking configuration commit

 * drm_atomic_nonblocking_commit - atomic nonblocking commit

 * @state: atomic configuration to check

 *

 * Note that this function can return -EDEADLK if the driver needed to acquire
@@ -1829,10 +1825,10 @@ static int atomic_set_prop(struct drm_atomic_state *state, 
 * @plane_mask: plane mask for planes that were updated.

 * @ret: return value, can be -EDEADLK for a retry.

 *

 * Before doing an update plane->old_fb is set to plane->fb,

 * but before dropping the locks old_fb needs to be set to NULL

 * and plane->fb updated. This is a common operation for each

 * atomic update, so this call is split off as a helper.

 * Before doing an update &drm_plane.old_fb is set to &drm_plane.fb, but before

 * dropping the locks old_fb needs to be set to NULL and plane->fb updated. This

 * is a common operation for each atomic update, so this call is split off as a

 * helper.

 */

void drm_atomic_clean_old_fb(struct drm_device *dev,

			     unsigned plane_mask,
@@ -1873,7 +1869,7 @@ EXPORT_SYMBOL(drm_atomic_clean_old_fb); 
 * As a contrast, with implicit fencing the kernel keeps track of any

 * ongoing rendering, and automatically ensures that the atomic update waits

 * for any pending rendering to complete. For shared buffers represented with

 * a &struct dma_buf this is tracked in &reservation_object structures.

 * a &struct dma_buf this is tracked in &struct reservation_object.

 * Implicit syncing is how Linux traditionally worked (e.g. DRI2/3 on X.org),

 * whereas explicit fencing is what Android wants.

 *

drivers/gpu/drm/drm_blend.c

+5 −6
Original line number Diff line number Diff line
@@ -40,9 +40,8 @@ 
 * sub-pixel accuracy, which is scaled up to a pixel-aligned destination

 * rectangle in the visible area of a &drm_crtc. The visible area of a CRTC is

 * defined by the horizontal and vertical visible pixels (stored in @hdisplay

 * and @vdisplay) of the requested mode (stored in @mode in the

 * &drm_crtc_state). These two rectangles are both stored in the

 * &drm_plane_state.

 * and @vdisplay) of the requested mode (stored in &drm_crtc_state.mode). These

 * two rectangles are both stored in the &drm_plane_state.

 *

 * For the atomic ioctl the following standard (atomic) properties on the plane object

 * encode the basic plane composition model:
@@ -215,7 +214,7 @@ EXPORT_SYMBOL(drm_rotation_simplify); 
 * for it in drm core. Drivers can then attach this property to planes to enable

 * support for configurable planes arrangement during blending operation.

 * Once mutable zpos property has been enabled, the DRM core will automatically

 * calculate drm_plane_state->normalized_zpos values. Usually min should be set

 * calculate &drm_plane_state.normalized_zpos values. Usually min should be set

 * to 0 and max to maximal number of planes for given crtc - 1.

 *

 * If zpos of some planes cannot be changed (like fixed background or
@@ -367,8 +366,8 @@ done: 
 * For every CRTC this function checks new states of all planes assigned to

 * it and calculates normalized zpos value for these planes. Planes are compared

 * first by their zpos values, then by plane id (if zpos is equal). The plane

 * with lowest zpos value is at the bottom. The plane_state->normalized_zpos is

 * then filled with unique values from 0 to number of active planes in crtc

 * with lowest zpos value is at the bottom. The &drm_plane_state.normalized_zpos

 * is then filled with unique values from 0 to number of active planes in crtc

 * minus one.

 *

 * RETURNS

drivers/gpu/drm/drm_connector.c

+6 −6
Original line number Diff line number Diff line
@@ -38,8 +38,8 @@ 
 * Hence they are reference-counted using drm_connector_reference() and

 * drm_connector_unreference().

 *

 * KMS driver must create, initialize, register and attach at a struct

 * &drm_connector for each such sink. The instance is created as other KMS

 * KMS driver must create, initialize, register and attach at a &struct

 * drm_connector for each such sink. The instance is created as other KMS

 * objects and initialized by setting the following fields.

 *

 * The connector is then registered with a call to drm_connector_init() with a
@@ -49,7 +49,7 @@ 
 * Connectors must be attached to an encoder to be used. For devices that map

 * connectors to encoders 1:1, the connector should be attached at

 * initialization time with a call to drm_mode_connector_attach_encoder(). The

 * driver must also set the &struct drm_connector encoder field to point to the

 * driver must also set the &drm_connector.encoder field to point to the

 * attached encoder.

 *

 * For connectors which are not fixed (like built-in panels) the driver needs to
@@ -497,7 +497,7 @@ static struct lockdep_map connector_list_iter_dep_map = { 
 * @dev: DRM device

 * @iter: connector_list iterator

 *

 * Sets @iter up to walk the connector list in &drm_mode_config of @dev. @iter

 * Sets @iter up to walk the &drm_mode_config.connector_list of @dev. @iter

 * must always be cleaned up again by calling drm_connector_list_iter_put().

 * Iteration itself happens using drm_connector_list_iter_next() or

 * drm_for_each_connector_iter().
@@ -696,8 +696,8 @@ DRM_ENUM_NAME_FN(drm_get_tv_subconnector_name, 
 * 	drivers this is only provided for backwards compatibility with existing

 * 	drivers, it remaps to controlling the "ACTIVE" property on the CRTC the

 * 	connector is linked to. Drivers should never set this property directly,

 * 	it is handled by the DRM core by calling the ->dpms() callback in

 * 	&drm_connector_funcs. Atomic drivers should implement this hook using

 * 	it is handled by the DRM core by calling the &drm_connector_funcs.dpms

 * 	callback. Atomic drivers should implement this hook using

 * 	drm_atomic_helper_connector_dpms(). This is the only property standard

 * 	connector property that userspace can change.

 * PATH:

drivers/gpu/drm/drm_crtc.c

+4 −3
Original line number Diff line number Diff line
@@ -415,11 +415,12 @@ int drm_mode_getcrtc(struct drm_device *dev, 
}



/**

 * drm_mode_set_config_internal - helper to call ->set_config

 * drm_mode_set_config_internal - helper to call &drm_mode_config_funcs.set_config

 * @set: modeset config to set

 *

 * This is a little helper to wrap internal calls to the ->set_config driver

 * interface. The only thing it adds is correct refcounting dance.

 * This is a little helper to wrap internal calls to the

 * &drm_mode_config_funcs.set_config driver interface. The only thing it adds is

 * correct refcounting dance.

 *

 * Returns:

 * Zero on success, negative errno on failure.

drivers/gpu/drm/drm_dumb_buffers.c

+2 −2
Original line number Diff line number Diff line
@@ -42,8 +42,8 @@ 
 * create dumb buffers suitable for scanout, which can then be used to create

 * KMS frame buffers.

 *

 * To support dumb objects drivers must implement the dumb_create,

 * dumb_destroy and dumb_map_offset operations from &struct drm_driver. See

 * To support dumb objects drivers must implement the &drm_driver.dumb_create,

 * &drm_driver.dumb_destroy and &drm_driver.dumb_map_offset operations. See

 * there for further details.

 *

 * Note that dumb objects may not be used for gpu acceleration, as has been

CRA Git | Maintained and supported by SUSTech CRA and CCSE