From d574528a64c3a3b2a9c6a125e2428b38bddbdf3c Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Wed, 25 Jan 2017 07:26:45 +0100 Subject: 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 Cc: Chris Wilson Reviewed-by: Eric Engestrom Signed-off-by: Daniel Vetter Link: http://patchwork.freedesktop.org/patch/msgid/20170125062657.19270-4-daniel.vetter@ffwll.ch --- include/drm/drm_atomic.h | 6 ++++-- include/drm/drm_color_mgmt.h | 2 +- include/drm/drm_connector.h | 42 +++++++++++++++++++++--------------------- include/drm/drm_crtc.h | 31 ++++++++++++++++--------------- include/drm/drm_framebuffer.h | 15 +++++++-------- include/drm/drm_mode_config.h | 12 ++++++------ include/drm/drm_mode_object.h | 13 +++++++++---- include/drm/drm_modeset_lock.h | 2 +- include/drm/drm_plane.h | 22 +++++++++++----------- include/drm/drm_property.h | 8 ++++---- 10 files changed, 80 insertions(+), 73 deletions(-) (limited to 'include') diff --git a/include/drm/drm_atomic.h b/include/drm/drm_atomic.h index f96220ed4004..2e28fdca9c3d 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 c767238ac9d5..d9c2f680f5ae 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 d489cc003b7e..e5e1eddd19fb 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 06c943d1e04c..10661e156d89 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 046c35e54099..04c77eee9c20 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 17942c0f32a8..5a29978062d3 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 43460b21d112..2c017adf6d74 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 d918ce45ec2c..96d39fbd12ca 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 e049bc52fb07..6834d61eec30 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 43c4b6a2046d..f66fdb47551c 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 * -- cgit v1.2.3