drm/kms-core: Use recommened kerneldoc for struct member refs
authorDaniel Vetter <daniel.vetter@ffwll.ch>
Wed, 25 Jan 2017 06:26:45 +0000 (07:26 +0100)
committerDaniel Vetter <daniel.vetter@ffwll.ch>
Wed, 25 Jan 2017 15:30:34 +0000 (16:30 +0100)
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: Eric Engestrom <eric.engestrom@imgtec.com>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Link: http://patchwork.freedesktop.org/patch/msgid/20170125062657.19270-4-daniel.vetter@ffwll.ch
21 files changed:
drivers/gpu/drm/drm_atomic.c
drivers/gpu/drm/drm_blend.c
drivers/gpu/drm/drm_connector.c
drivers/gpu/drm/drm_crtc.c
drivers/gpu/drm/drm_dumb_buffers.c
drivers/gpu/drm/drm_encoder.c
drivers/gpu/drm/drm_encoder_slave.c
drivers/gpu/drm/drm_framebuffer.c
drivers/gpu/drm/drm_modeset_lock.c
drivers/gpu/drm/drm_plane.c
drivers/gpu/drm/drm_property.c
include/drm/drm_atomic.h
include/drm/drm_color_mgmt.h
include/drm/drm_connector.h
include/drm/drm_crtc.h
include/drm/drm_framebuffer.h
include/drm/drm_mode_config.h
include/drm/drm_mode_object.h
include/drm/drm_modeset_lock.h
include/drm/drm_plane.h
include/drm/drm_property.h

index 6414bcf7f41bcfb2c13df2e6e8a2157b13701945..7fd88a09304b0d7968d1997b35eedf58a0e8b3b9 100644 (file)
@@ -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.
  *
index 1f2412c7ccfdb2929555c63bec6e3ccf136589f8..665aafc6ad68cc7cfc6e3688ac82082e0ac23463 100644 (file)
@@ -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
index 799edd0d308e1d599938de48c1f6cf84ee2814e1..dd720d4cb4f7bb15ad03fa77debc404d7fd7ed8d 100644 (file)
@@ -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:
index bd3c8b24344761cf4d460c34dda47a130384afdc..cea7a7efa43c903769f08a2f198691cd11af1a5c 100644 (file)
@@ -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.
index e5c61cda4ae32a045d590fb32f886156385ff47c..10307cc16d7589949ac6ce8a5037b2e8724710c6 100644 (file)
@@ -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
index 487cfe3989e8555861f8797db99da5c59617cc32..129450713bb783a062638988d16a22b63c7fc7f1 100644 (file)
@@ -98,7 +98,7 @@ void drm_encoder_unregister_all(struct drm_device *dev)
  *
  * Initialises a preallocated encoder. Encoder should be subclassed as part of
  * driver encoder objects. At driver unload time drm_encoder_cleanup() should be
- * called from the driver's destroy hook in &drm_encoder_funcs.
+ * called from the driver's &drm_encoder_funcs.destroy hook.
  *
  * Returns:
  * Zero on success, error code on failure.
index 4484785cd9ac22a45fd8a2dcf95d54d2e22fde99..cf804389f5ecad3ea7589fc0d074ec6c12578ca6 100644 (file)
@@ -43,7 +43,7 @@
  * &drm_encoder_slave. The @slave_funcs field will be initialized with
  * the hooks provided by the slave driver.
  *
- * If @info->platform_data is non-NULL it will be used as the initial
+ * If @info.platform_data is non-NULL it will be used as the initial
  * slave config.
  *
  * Returns 0 on success or a negative errno on failure, in particular,
index 588ccc3a22181b496cea4c6a43a5c16ccf8d48bb..28a0108a1ab85f9a4fbd87c39bff668027597585 100644 (file)
@@ -58,8 +58,8 @@
  * fbdev framebuffer when the struct &struct drm_framebuffer is embedded into
  * the fbdev helper struct) drivers can manually clean up a framebuffer at
  * module unload time with drm_framebuffer_unregister_private(). But doing this
- * is not recommended, and it's better to have a normal free-standing struct
- * &drm_framebuffer.
+ * is not recommended, and it's better to have a normal free-standing &struct
+ * drm_framebuffer.
  */
 
 int drm_framebuffer_check_src_coords(uint32_t src_x, uint32_t src_y,
@@ -470,7 +470,7 @@ int drm_mode_getfb(struct drm_device *dev,
  * usb display-link, mipi manual update panels or edp panel self refresh modes.
  *
  * Modesetting drivers which always update the frontbuffer do not need to
- * implement the corresponding ->dirty framebuffer callback.
+ * implement the corresponding &drm_framebuffer_funcs.dirty callback.
  *
  * Called by the user via ioctl.
  *
@@ -709,10 +709,10 @@ EXPORT_SYMBOL(drm_framebuffer_unregister_private);
  * @fb: framebuffer to remove
  *
  * Cleanup framebuffer. This function is intended to be used from the drivers
- * ->destroy callback. It can also be used to clean up driver private
- * framebuffers embedded into a larger structure.
+ * &drm_framebuffer_funcs.destroy callback. It can also be used to clean up
+ * driver private framebuffers embedded into a larger structure.
  *
- * Note that this function does not remove the fb from active usuage - if it is
+ * Note that this function does not remove the fb from active usage - if it is
  * still used anywhere, hilarity can ensue since userspace could call getfb on
  * the id and get back -EINVAL. Obviously no concern at driver unload time.
  *
index 3551ae31f143f36c70712ae80ec31e3494dafcda..bf60f2645e55374d7ea79f102a64d656ac92f49b 100644 (file)
@@ -33,7 +33,7 @@
  * to use &ww_mutex and acquire-contexts to avoid deadlocks.  But because
  * the locking is more distributed around the driver code, we want a bit
  * of extra utility/tracking out of our acquire-ctx.  This is provided
- * by drm_modeset_lock / drm_modeset_acquire_ctx.
+ * by &struct drm_modeset_lock and &struct drm_modeset_acquire_ctx.
  *
  * For basic principles of &ww_mutex, see: Documentation/locking/ww-mutex-design.txt
  *
@@ -53,7 +53,7 @@
  *     drm_modeset_acquire_fini(&ctx);
  *
  * On top of of these per-object locks using &ww_mutex there's also an overall
- * dev->mode_config.lock, for protecting everything else. Mostly this means
+ * &drm_mode_config.mutex, for protecting everything else. Mostly this means
  * probe state of connectors, and preventing hotplug add/removal of connectors.
  *
  * Finally there's a bunch of dedicated locks to protect drm core internal
@@ -71,7 +71,7 @@ static DEFINE_WW_CLASS(crtc_ww_class);
  * drm_modeset_unlock_all() function.
  *
  * This function is deprecated. It allocates a lock acquisition context and
- * stores it in the DRM device's ->mode_config. This facilitate conversion of
+ * stores it in &drm_device.mode_config. This facilitate conversion of
  * existing code because it removes the need to manually deal with the
  * acquisition context, but it is also brittle because the context is global
  * and care must be taken not to nest calls. New code should use the
@@ -124,7 +124,7 @@ EXPORT_SYMBOL(drm_modeset_lock_all);
  * drm_modeset_lock_all() function.
  *
  * This function is deprecated. It uses the lock acquisition context stored
- * in the DRM device's ->mode_config. This facilitates conversion of existing
+ * in &drm_device.mode_config. This facilitates conversion of existing
  * code because it removes the need to manually deal with the acquisition
  * context, but it is also brittle because the context is global and care must
  * be taken not to nest calls. New code should pass the acquisition context
@@ -468,7 +468,7 @@ EXPORT_SYMBOL(drm_modeset_unlock);
  * This function takes all modeset locks, suitable where a more fine-grained
  * scheme isn't (yet) implemented.
  *
- * Unlike drm_modeset_lock_all(), it doesn't take the dev->mode_config.mutex
+ * Unlike drm_modeset_lock_all(), it doesn't take the &drm_mode_config.mutex
  * since that lock isn't required for modeset state changes. Callers which
  * need to grab that lock too need to do so outside of the acquire context
  * @ctx.
index eed66be183299d9e02c76f231c46f7e9acd2e30d..c464fc4a874d239907dfa9f6b54d27813e821ed3 100644 (file)
@@ -42,7 +42,7 @@
  *
  * Cursor and overlay planes are optional. All drivers should provide one
  * primary plane per CRTC to avoid surprising userspace too much. See enum
- * &drm_plane_type for a more in-depth discussion of these special uapi-relevant
+ * drm_plane_type for a more in-depth discussion of these special uapi-relevant
  * plane types. Special planes are associated with their CRTC by calling
  * drm_crtc_init_with_planes().
  *
index 0d0e5dc0ee239b0dba9c9cbe29c2a1b76daa5ea6..7fc070f3e49e3e1a87b435641661e4af38c83213 100644 (file)
@@ -42,8 +42,8 @@
  * drm_object_attach_property().
  *
  * Property values are only 64bit. To support bigger piles of data (like gamma
- * tables, color correction matrizes or large structures) a property can instead
- * point at a &drm_property_blob with that additional data
+ * tables, color correction matrices or large structures) a property can instead
+ * point at a &drm_property_blob with that additional data.
  *
  * Properties are defined by their symbolic name, userspace must keep a
  * per-object mapping from those names to the property ID used in the atomic
index f96220ed40046e2ddc3e4a7cc0944119bde7ca28..2e28fdca9c3d293c56e4192d287e59e459ff80b4 100644 (file)
@@ -123,7 +123,8 @@ struct drm_crtc_commit {
        /**
         * @commit_entry:
         *
-        * Entry on the per-CRTC commit_list. Protected by crtc->commit_lock.
+        * Entry on the per-CRTC &drm_crtc.commit_list. Protected by
+        * $drm_crtc.commit_lock.
         */
        struct list_head commit_entry;
 
@@ -429,7 +430,8 @@ void drm_state_dump(struct drm_device *dev, struct drm_printer *p);
  *
  * For example if the CRTC mode has changed, and the hardware is able to enact
  * the requested mode change without going through a full modeset, the driver
- * should clear mode_changed during its ->atomic_check.
+ * should clear mode_changed in its &drm_mode_config_funcs.atomic_check
+ * implementation.
  */
 static inline bool
 drm_atomic_crtc_needs_modeset(const struct drm_crtc_state *state)
index c767238ac9d593f65b279a85b9b5feda8db6cee4..d9c2f680f5aeb8d879e2e8ff80485e5c5e9e8f2f 100644 (file)
@@ -34,7 +34,7 @@ int drm_mode_crtc_set_gamma_size(struct drm_crtc *crtc,
                                 int gamma_size);
 
 /**
- * drm_color_lut_extract - clamp&round LUT entries
+ * drm_color_lut_extract - clamp and round LUT entries
  * @user_input: input value
  * @bit_precision: number of bits the hw LUT supports
  *
index d489cc003b7eebc8740a2d6d8316e05e1cd8b754..e5e1eddd19fb19d168a18fb2607c0a5c81e2ec37 100644 (file)
@@ -331,15 +331,15 @@ struct drm_connector_funcs {
         *
         * Entry point for output detection and basic mode validation. The
         * driver should reprobe the output if needed (e.g. when hotplug
-        * handling is unreliable), add all detected modes to connector->modes
+        * handling is unreliable), add all detected modes to &drm_connector.modes
         * and filter out any the device can't support in any configuration. It
         * also needs to filter out any modes wider or higher than the
         * parameters max_width and max_height indicate.
         *
         * The drivers must also prune any modes no longer valid from
-        * connector->modes. Furthermore it must update connector->status and
-        * connector->edid.  If no EDID has been received for this output
-        * connector->edid must be NULL.
+        * &drm_connector.modes. Furthermore it must update
+        * &drm_connector.status and &drm_connector.edid.  If no EDID has been
+        * received for this output connector->edid must be NULL.
         *
         * Drivers using the probe helpers should use
         * drm_helper_probe_single_connector_modes() or
@@ -348,7 +348,7 @@ struct drm_connector_funcs {
         *
         * RETURNS:
         *
-        * The number of modes detected and filled into connector->modes.
+        * The number of modes detected and filled into &drm_connector.modes.
         */
        int (*fill_modes)(struct drm_connector *connector, uint32_t max_width, uint32_t max_height);
 
@@ -381,7 +381,7 @@ struct drm_connector_funcs {
         * core drm connector interfaces. Everything added from this callback
         * should be unregistered in the early_unregister callback.
         *
-        * This is called while holding drm_connector->mutex.
+        * This is called while holding &drm_connector.mutex.
         *
         * Returns:
         *
@@ -398,7 +398,7 @@ struct drm_connector_funcs {
         * early in the driver unload sequence to disable userspace access
         * before data structures are torndown.
         *
-        * This is called while holding drm_connector->mutex.
+        * This is called while holding &drm_connector.mutex.
         */
        void (*early_unregister)(struct drm_connector *connector);
 
@@ -418,9 +418,9 @@ struct drm_connector_funcs {
         * Duplicate the current atomic state for this connector and return it.
         * The core and helpers guarantee that any atomic state duplicated with
         * this hook and still owned by the caller (i.e. not transferred to the
-        * driver by calling ->atomic_commit() from struct
-        * &drm_mode_config_funcs) will be cleaned up by calling the
-        * @atomic_destroy_state hook in this structure.
+        * driver by calling &drm_mode_config_funcs.atomic_commit) will be
+        * cleaned up by calling the @atomic_destroy_state hook in this
+        * structure.
         *
         * Atomic drivers which don't subclass &struct drm_connector_state should use
         * drm_atomic_helper_connector_duplicate_state(). Drivers that subclass the
@@ -428,7 +428,7 @@ struct drm_connector_funcs {
         * __drm_atomic_helper_connector_duplicate_state() to make sure shared state is
         * duplicated in a consistent fashion across drivers.
         *
-        * It is an error to call this hook before connector->state has been
+        * It is an error to call this hook before &drm_connector.state has been
         * initialized correctly.
         *
         * NOTE:
@@ -609,8 +609,8 @@ struct drm_connector {
 
        /**
         * @mutex: Lock for general connector state, but currently only protects
-        * @registered. Most of the connector state is still protected by the
-        * mutex in &drm_mode_config.
+        * @registered. Most of the connector state is still protected by
+        * &drm_mode_config.mutex.
         */
        struct mutex mutex;
 
@@ -636,22 +636,22 @@ struct drm_connector {
        /**
         * @modes:
         * Modes available on this connector (from fill_modes() + user).
-        * Protected by dev->mode_config.mutex.
+        * Protected by &drm_mode_config.mutex.
         */
-       struct list_head modes; /* list of modes on this connector */
+       struct list_head modes;
 
        /**
         * @status:
         * One of the drm_connector_status enums (connected, not, or unknown).
-        * Protected by dev->mode_config.mutex.
+        * Protected by &drm_mode_config.mutex.
         */
        enum drm_connector_status status;
 
        /**
         * @probed_modes:
         * These are modes added by probing with DDC or the BIOS, before
-        * filtering is applied. Used by the probe helpers.Protected by
-        * dev->mode_config.mutex.
+        * filtering is applied. Used by the probe helpers. Protected by
+        * &drm_mode_config.mutex.
         */
        struct list_head probed_modes;
 
@@ -659,10 +659,10 @@ struct drm_connector {
         * @display_info: Display information is filled from EDID information
         * when a display is detected. For non hot-pluggable displays such as
         * flat panels in embedded systems, the driver should initialize the
-        * display_info.width_mm and display_info.height_mm fields with the
-        * physical size of the display.
+        * &drm_display_info.width_mm and &drm_display_info.height_mm fields
+        * with the physical size of the display.
         *
-        * Protected by dev->mode_config.mutex.
+        * Protected by &drm_mode_config.mutex.
         */
        struct drm_display_info display_info;
        const struct drm_connector_funcs *funcs;
index 06c943d1e04c2dfb18cec854e5f8f240fd722ad8..10661e156d89d617ccf71139bab898468734e952 100644 (file)
@@ -81,8 +81,8 @@ struct drm_plane_helper_funcs;
  * @enable: whether the CRTC should be enabled, gates all other state
  * @active: whether the CRTC is actively displaying (used for DPMS)
  * @planes_changed: planes on this crtc are updated
- * @mode_changed: crtc_state->mode or crtc_state->enable has been changed
- * @active_changed: crtc_state->active has been toggled.
+ * @mode_changed: @mode or @enable has been changed
+ * @active_changed: @active has been toggled.
  * @connectors_changed: connectors to this crtc have been updated
  * @zpos_changed: zpos values of planes on this crtc have been updated
  * @color_mgmt_changed: color management properties have changed (degamma or
@@ -102,9 +102,10 @@ struct drm_plane_helper_funcs;
  *
  * Note that the distinction between @enable and @active is rather subtile:
  * Flipping @active while @enable is set without changing anything else may
- * never return in a failure from the ->atomic_check callback. Userspace assumes
- * that a DPMS On will always succeed. In other words: @enable controls resource
- * assignment, @active controls the actual hardware state.
+ * never return in a failure from the &drm_mode_config_funcs.atomic_check
+ * callback. Userspace assumes that a DPMS On will always succeed. In other
+ * words: @enable controls resource assignment, @active controls the actual
+ * hardware state.
  *
  * The three booleans active_changed, connectors_changed and mode_changed are
  * intended to indicate whether a full modeset is needed, rather than strictly
@@ -346,8 +347,8 @@ struct drm_crtc_funcs {
         * through the DRM_MODE_PAGE_FLIP_ASYNC flag). When an application
         * requests a page flip the DRM core verifies that the new frame buffer
         * is large enough to be scanned out by the CRTC in the currently
-        * configured mode and then calls the CRTC ->page_flip() operation with a
-        * pointer to the new frame buffer.
+        * configured mode and then calls this hook with a pointer to the new
+        * frame buffer.
         *
         * The driver must wait for any pending rendering to the new framebuffer
         * to complete before executing the flip. It should also wait for any
@@ -382,7 +383,7 @@ struct drm_crtc_funcs {
         * RETURNS:
         *
         * 0 on success or a negative error code on failure. Note that if a
-        * ->page_flip() operation is already pending the callback should return
+        * page flip operation is already pending the callback should return
         * -EBUSY. Pageflips on a disabled CRTC (either by setting a NULL mode
         * or just runtime disabled through DPMS respectively the new atomic
         * "ACTIVE" state) should result in an -EINVAL error code. Note that
@@ -434,19 +435,19 @@ struct drm_crtc_funcs {
         * @atomic_duplicate_state:
         *
         * Duplicate the current atomic state for this CRTC and return it.
-        * The core and helpers gurantee that any atomic state duplicated with
+        * The core and helpers guarantee that any atomic state duplicated with
         * this hook and still owned by the caller (i.e. not transferred to the
-        * driver by calling ->atomic_commit() from struct
-        * &drm_mode_config_funcs) will be cleaned up by calling the
-        * @atomic_destroy_state hook in this structure.
+        * driver by calling &drm_mode_config_funcs.atomic_commit) will be
+        * cleaned up by calling the @atomic_destroy_state hook in this
+        * structure.
         *
-        * Atomic drivers which don't subclass &struct drm_crtc should use
+        * Atomic drivers which don't subclass &struct drm_crtc_state should use
         * drm_atomic_helper_crtc_duplicate_state(). Drivers that subclass the
         * state structure to extend it with driver-private state should use
         * __drm_atomic_helper_crtc_duplicate_state() to make sure shared state is
         * duplicated in a consistent fashion across drivers.
         *
-        * It is an error to call this hook before crtc->state has been
+        * It is an error to call this hook before &drm_crtc.state has been
         * initialized correctly.
         *
         * NOTE:
@@ -641,7 +642,7 @@ struct drm_crtc {
         * This provides a read lock for the overall crtc state (mode, dpms
         * state, ...) and a write lock for everything which can be update
         * without a full modeset (fb, cursor data, crtc properties ...). Full
-        * modeset also need to grab dev->mode_config.connection_mutex.
+        * modeset also need to grab &drm_mode_config.connection_mutex.
         */
        struct drm_modeset_lock mutex;
 
index 046c35e540994ef4c706093f4e23f5ecac4612bd..04c77eee9c20930dea4672be8080b95c8a509606 100644 (file)
@@ -40,8 +40,8 @@ struct drm_framebuffer_funcs {
         *
         * Clean up framebuffer resources, specifically also unreference the
         * backing storage. The core guarantees to call this function for every
-        * framebuffer successfully created by ->fb_create() in
-        * &drm_mode_config_funcs. Drivers must also call
+        * framebuffer successfully created by calling
+        * &drm_mode_config_funcs.fb_create. Drivers must also call
         * drm_framebuffer_cleanup() to release DRM core resources for this
         * framebuffer.
         */
@@ -112,8 +112,8 @@ struct drm_framebuffer {
         */
        struct drm_device *dev;
        /**
-        * @head: Place on the dev->mode_config.fb_list, access protected by
-        * dev->mode_config.fb_lock.
+        * @head: Place on the &drm_mode_config.fb_list, access protected by
+        * &drm_mode_config.fb_lock.
         */
        struct list_head head;
 
@@ -187,8 +187,7 @@ struct drm_framebuffer {
         */
        int hot_y;
        /**
-        * @filp_head: Placed on &struct drm_file fbs list_head, protected by
-        * fbs_lock in the same structure.
+        * @filp_head: Placed on &drm_file.fbs, protected by &drm_file.fbs_lock.
         */
        struct list_head filp_head;
 };
@@ -260,8 +259,8 @@ static inline void drm_framebuffer_assign(struct drm_framebuffer **p,
  * @fb: the loop cursor
  * @dev: the DRM device
  *
- * Iterate over all framebuffers of @dev. User must hold the fb_lock from
- * &drm_mode_config.
+ * Iterate over all framebuffers of @dev. User must hold
+ * &drm_mode_config.fb_lock.
  */
 #define drm_for_each_fb(fb, dev) \
        for (WARN_ON(!mutex_is_locked(&(dev)->mode_config.fb_lock)),            \
index 17942c0f32a89278d03f74d733da467656ba8304..5a29978062d3c6b996e44ca2ae04f6b524bc3d70 100644 (file)
@@ -132,8 +132,8 @@ struct drm_mode_config_funcs {
         *    that before calling this hook.
         *
         * See the documentation of @atomic_commit for an exhaustive list of
-        * error conditions which don't have to be checked at the
-        * ->atomic_check() stage?
+        * error conditions which don't have to be checked at the in this
+        * callback.
         *
         * See the documentation for &struct drm_atomic_state for how exactly
         * an atomic modeset update is described.
@@ -198,10 +198,10 @@ struct drm_mode_config_funcs {
         * completed. These events are per-CRTC and can be distinguished by the
         * CRTC index supplied in &drm_event to userspace.
         *
-        * The drm core will supply a &struct drm_event in the event
-        * member of each CRTC's &drm_crtc_state structure. See the
-        * documentation for &drm_crtc_state for more details about the precise
-        * semantics of this event.
+        * The drm core will supply a &struct drm_event in each CRTC's
+        * &drm_crtc_state.event. See the documentation for
+        * &drm_crtc_state.event for more details about the precise semantics of
+        * this event.
         *
         * NOTE:
         *
index 43460b21d112f3067aa85f56f650abb144eebfe9..2c017adf6d744a68a98db117e7d3aef4af69051e 100644 (file)
@@ -86,10 +86,15 @@ struct drm_object_properties {
         *
         * Note that atomic drivers do not store mutable properties in this
         * array, but only the decoded values in the corresponding state
-        * structure. The decoding is done using the ->atomic_get_property and
-        * ->atomic_set_property hooks of the corresponding object. Hence atomic
-        * drivers should not use drm_object_property_set_value() and
-        * drm_object_property_get_value() on mutable objects, i.e. those
+        * structure. The decoding is done using the &drm_crtc.atomic_get_property and
+        * &drm_crtc.atomic_set_property hooks for &struct drm_crtc. For
+        * &struct drm_plane the hooks are &drm_plane_funcs.atomic_get_property and
+        * &drm_plane_funcs.atomic_set_property. And for &struct drm_connector
+        * the hooks are &drm_connector_funcs.atomic_get_property and
+        * &drm_connector_funcs.atomic_set_property .
+        *
+        * Hence atomic drivers should not use drm_object_property_set_value()
+        * and drm_object_property_get_value() on mutable objects, i.e. those
         * without the DRM_MODE_PROP_IMMUTABLE flag set.
         */
        uint64_t values[DRM_OBJECT_MAX_PROPERTY];
index d918ce45ec2c089ef673f8e48de079457cfdc3ba..96d39fbd12cacd9ae0a1d8730c93f439b5837459 100644 (file)
@@ -64,7 +64,7 @@ struct drm_modeset_acquire_ctx {
 /**
  * struct drm_modeset_lock - used for locking modeset resources.
  * @mutex: resource locking
- * @head: used to hold it's place on state->locked list when
+ * @head: used to hold it's place on &drm_atomi_state.locked list when
  *    part of an atomic update
  *
  * Used for locking CRTCs and other modeset resources.
index e049bc52fb07579fd1cbae9caeae0eb08ab48f33..6834d61eec300f517a8cec06ccb214e5634d6a65 100644 (file)
@@ -247,11 +247,11 @@ struct drm_plane_funcs {
         * @atomic_duplicate_state:
         *
         * Duplicate the current atomic state for this plane and return it.
-        * The core and helpers gurantee that any atomic state duplicated with
+        * The core and helpers guarantee that any atomic state duplicated with
         * this hook and still owned by the caller (i.e. not transferred to the
-        * driver by calling ->atomic_commit() from struct
-        * &drm_mode_config_funcs) will be cleaned up by calling the
-        * @atomic_destroy_state hook in this structure.
+        * driver by calling &drm_mode_config_funcs.atomic_commit) will be
+        * cleaned up by calling the @atomic_destroy_state hook in this
+        * structure.
         *
         * Atomic drivers which don't subclass &struct drm_plane_state should use
         * drm_atomic_helper_plane_duplicate_state(). Drivers that subclass the
@@ -259,7 +259,7 @@ struct drm_plane_funcs {
         * __drm_atomic_helper_plane_duplicate_state() to make sure shared state is
         * duplicated in a consistent fashion across drivers.
         *
-        * It is an error to call this hook before plane->state has been
+        * It is an error to call this hook before &drm_plane.state has been
         * initialized correctly.
         *
         * NOTE:
@@ -423,8 +423,8 @@ enum drm_plane_type {
         *
         * Primary planes represent a "main" plane for a CRTC.  Primary planes
         * are the planes operated upon by CRTC modesetting and flipping
-        * operations described in the page_flip and set_config hooks in struct
-        * &drm_crtc_funcs.
+        * operations described in the &drm_crtc_funcs.page_flip and
+        * &drm_crtc_funcs.set_config hooks.
         */
        DRM_PLANE_TYPE_PRIMARY,
 
@@ -470,9 +470,9 @@ struct drm_plane {
        /**
         * @mutex:
         *
-        * Protects modeset plane state, together with the mutex of &drm_crtc
-        * this plane is linked to (when active, getting actived or getting
-        * disabled).
+        * Protects modeset plane state, together with the &drm_crtc.mutex of
+        * CRTC this plane is linked to (when active, getting activated or
+        * getting disabled).
         */
        struct drm_modeset_lock mutex;
 
@@ -580,7 +580,7 @@ static inline struct drm_plane *drm_plane_find(struct drm_device *dev,
  *
  * Iterate over all legacy planes of @dev, excluding primary and cursor planes.
  * This is useful for implementing userspace apis when userspace is not
- * universal plane aware. See also enum &drm_plane_type.
+ * universal plane aware. See also &enum drm_plane_type.
  */
 #define drm_for_each_legacy_plane(plane, dev) \
        list_for_each_entry(plane, &(dev)->mode_config.plane_list, head) \
index 43c4b6a2046d6c8cc03636cdde0879193dd3899f..f66fdb47551cea64146b568303d3e164ab47ddde 100644 (file)
@@ -30,7 +30,7 @@
 /**
  * struct drm_property_enum - symbolic values for enumerations
  * @value: numeric property value for this enum entry
- * @head: list of enum values, linked to enum_list in &drm_property
+ * @head: list of enum values, linked to &drm_property.enum_list
  * @name: symbolic name for the enum
  *
  * For enumeration and bitmask properties this structure stores the symbolic
@@ -191,9 +191,9 @@ struct drm_property {
  * struct drm_property_blob - Blob data for &drm_property
  * @base: base KMS object
  * @dev: DRM device
- * @head_global: entry on the global blob list in &drm_mode_config
- *     property_blob_list.
- * @head_file: entry on the per-file blob list in &drm_file blobs list.
+ * @head_global: entry on the global blob list in
+ *     &drm_mode_config.property_blob_list.
+ * @head_file: entry on the per-file blob list in &drm_file.blobs list.
  * @length: size of the blob in bytes, invariant over the lifetime of the object
  * @data: actual data, embedded at the end of this structure
  *