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: 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
diff --git a/include/drm/drm_atomic.h b/include/drm/drm_atomic.h
index f96220e..2e28fdc 100644
--- a/include/drm/drm_atomic.h
+++ b/include/drm/drm_atomic.h
@@ -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)
diff --git a/include/drm/drm_color_mgmt.h b/include/drm/drm_color_mgmt.h
index c767238..d9c2f68 100644
--- a/include/drm/drm_color_mgmt.h
+++ b/include/drm/drm_color_mgmt.h
@@ -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
*
diff --git a/include/drm/drm_connector.h b/include/drm/drm_connector.h
index d489cc0..e5e1edd 100644
--- a/include/drm/drm_connector.h
+++ b/include/drm/drm_connector.h
@@ -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;
diff --git a/include/drm/drm_crtc.h b/include/drm/drm_crtc.h
index 06c943d..10661e1 100644
--- a/include/drm/drm_crtc.h
+++ b/include/drm/drm_crtc.h
@@ -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;
diff --git a/include/drm/drm_framebuffer.h b/include/drm/drm_framebuffer.h
index 046c35e..04c77ee 100644
--- a/include/drm/drm_framebuffer.h
+++ b/include/drm/drm_framebuffer.h
@@ -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)), \
diff --git a/include/drm/drm_mode_config.h b/include/drm/drm_mode_config.h
index 17942c0..5a29978 100644
--- a/include/drm/drm_mode_config.h
+++ b/include/drm/drm_mode_config.h
@@ -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:
*
diff --git a/include/drm/drm_mode_object.h b/include/drm/drm_mode_object.h
index 43460b2..2c017ad 100644
--- a/include/drm/drm_mode_object.h
+++ b/include/drm/drm_mode_object.h
@@ -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];
diff --git a/include/drm/drm_modeset_lock.h b/include/drm/drm_modeset_lock.h
index d918ce4..96d39fb 100644
--- a/include/drm/drm_modeset_lock.h
+++ b/include/drm/drm_modeset_lock.h
@@ -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.
diff --git a/include/drm/drm_plane.h b/include/drm/drm_plane.h
index e049bc5..6834d61 100644
--- a/include/drm/drm_plane.h
+++ b/include/drm/drm_plane.h
@@ -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) \
diff --git a/include/drm/drm_property.h b/include/drm/drm_property.h
index 43c4b6a..f66fdb4 100644
--- a/include/drm/drm_property.h
+++ b/include/drm/drm_property.h
@@ -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
*