On Wednesday, 2017-01-25 07:26:45 +0100, Daniel Vetter wrote: > 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 ... > > Cc: Jani Nikula <jani.nikula@xxxxxxxxxxxxxxx> > Cc: Chris Wilson <chris@xxxxxxxxxxxxxxxxxx> > Signed-off-by: Daniel Vetter <daniel.vetter@xxxxxxxxx> > --- > drivers/gpu/drm/drm_atomic.c | 71 ++++++++++++++++++------------------- > drivers/gpu/drm/drm_blend.c | 11 +++--- > drivers/gpu/drm/drm_connector.c | 12 +++---- > drivers/gpu/drm/drm_crtc.c | 7 ++-- > drivers/gpu/drm/drm_dumb_buffers.c | 4 +-- > drivers/gpu/drm/drm_encoder.c | 2 +- > drivers/gpu/drm/drm_encoder_slave.c | 2 +- > drivers/gpu/drm/drm_framebuffer.c | 10 +++--- > drivers/gpu/drm/drm_modeset_lock.c | 10 +++--- > drivers/gpu/drm/drm_plane.c | 2 +- > drivers/gpu/drm/drm_property.c | 2 +- > include/drm/drm_atomic.h | 6 ++-- > include/drm/drm_color_mgmt.h | 2 +- > include/drm/drm_connector.h | 40 ++++++++++----------- > include/drm/drm_crtc.h | 29 +++++++-------- > 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 | 18 +++++----- > include/drm/drm_property.h | 8 ++--- > 21 files changed, 141 insertions(+), 137 deletions(-) > > diff --git a/drivers/gpu/drm/drm_atomic.c b/drivers/gpu/drm/drm_atomic.c > index 723392fc98c8..96c81a61a542 100644 > --- a/drivers/gpu/drm/drm_atomic.c > +++ b/drivers/gpu/drm/drm_atomic.c > @@ -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 > @@ -1316,8 +1313,8 @@ EXPORT_SYMBOL(drm_atomic_set_fb_for_plane); > * all drope the reference to the fence as we not storing it The sentence above could be rewritten as: "It will drop all reference to the fence as we are not storing it anywhere." > * anywhere. > * > - * Otherwise, if plane_state->fence is not set this function we > - * just set it with the received implict fence. > + * Otherwise, if &drm_plane_state.fence is not set this function we just set it > + * with the received implict fence. "implicit" > */ > void > drm_atomic_set_fence_for_plane(struct drm_plane_state *plane_state, > @@ -1616,7 +1613,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 +1826,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 +1870,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. > * > diff --git a/drivers/gpu/drm/drm_blend.c b/drivers/gpu/drm/drm_blend.c > index 1f2412c7ccfd..665aafc6ad68 100644 > --- a/drivers/gpu/drm/drm_blend.c > +++ b/drivers/gpu/drm/drm_blend.c > @@ -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 @@ static int drm_atomic_helper_crtc_normalize_zpos(struct drm_crtc *crtc, > * 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 > diff --git a/drivers/gpu/drm/drm_connector.c b/drivers/gpu/drm/drm_connector.c > index 799edd0d308e..dd720d4cb4f7 100644 > --- a/drivers/gpu/drm/drm_connector.c > +++ b/drivers/gpu/drm/drm_connector.c > @@ -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: > diff --git a/drivers/gpu/drm/drm_crtc.c b/drivers/gpu/drm/drm_crtc.c > index bd3c8b243447..cea7a7efa43c 100644 > --- a/drivers/gpu/drm/drm_crtc.c > +++ b/drivers/gpu/drm/drm_crtc.c > @@ -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. > diff --git a/drivers/gpu/drm/drm_dumb_buffers.c b/drivers/gpu/drm/drm_dumb_buffers.c > index e5c61cda4ae3..10307cc16d75 100644 > --- a/drivers/gpu/drm/drm_dumb_buffers.c > +++ b/drivers/gpu/drm/drm_dumb_buffers.c > @@ -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 > diff --git a/drivers/gpu/drm/drm_encoder.c b/drivers/gpu/drm/drm_encoder.c > index 487cfe3989e8..129450713bb7 100644 > --- a/drivers/gpu/drm/drm_encoder.c > +++ b/drivers/gpu/drm/drm_encoder.c > @@ -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. > diff --git a/drivers/gpu/drm/drm_encoder_slave.c b/drivers/gpu/drm/drm_encoder_slave.c > index 4484785cd9ac..cf804389f5ec 100644 > --- a/drivers/gpu/drm/drm_encoder_slave.c > +++ b/drivers/gpu/drm/drm_encoder_slave.c > @@ -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, > diff --git a/drivers/gpu/drm/drm_framebuffer.c b/drivers/gpu/drm/drm_framebuffer.c > index 588ccc3a2218..ca9cff09cad1 100644 > --- a/drivers/gpu/drm/drm_framebuffer.c > +++ b/drivers/gpu/drm/drm_framebuffer.c > @@ -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,8 +709,8 @@ 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 "usage" > * still used anywhere, hilarity can ensue since userspace could call getfb on > diff --git a/drivers/gpu/drm/drm_modeset_lock.c b/drivers/gpu/drm/drm_modeset_lock.c > index 3551ae31f143..bf60f2645e55 100644 > --- a/drivers/gpu/drm/drm_modeset_lock.c > +++ b/drivers/gpu/drm/drm_modeset_lock.c > @@ -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. > diff --git a/drivers/gpu/drm/drm_plane.c b/drivers/gpu/drm/drm_plane.c > index eed66be18329..c464fc4a874d 100644 > --- a/drivers/gpu/drm/drm_plane.c > +++ b/drivers/gpu/drm/drm_plane.c > @@ -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(). > * > diff --git a/drivers/gpu/drm/drm_property.c b/drivers/gpu/drm/drm_property.c > index 0d0e5dc0ee23..0cb2a39fe059 100644 > --- a/drivers/gpu/drm/drm_property.c > +++ b/drivers/gpu/drm/drm_property.c > @@ -43,7 +43,7 @@ > * > * Property values are only 64bit. To support bigger piles of data (like gamma > * tables, color correction matrizes or large structures) a property can instead "matrices" > - * point at a &drm_property_blob with that additional data > + * 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 > diff --git a/include/drm/drm_atomic.h b/include/drm/drm_atomic.h > index f1cb2b08afb5..052ab161b239 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..4f7d3b49995a 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,14 +636,14 @@ 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; > > @@ -651,7 +651,7 @@ struct drm_connector { > * @probed_modes: > * These are modes added by probing with DDC or the BIOS, before > * filtering is applied. Used by the probe helpers.Protected by space before "Protected" > - * dev->mode_config.mutex. > + * &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..496324d3416b 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 > @@ -436,17 +437,17 @@ struct drm_crtc_funcs { > * Duplicate the current atomic state for this CRTC and return it. > * The core and helpers gurantee that any atomic state duplicated with "guarantee" > * 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 fe230f161efc..26ff46ab26fb 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 "its", "drm_atomic_state" > * 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..525a3340c1b2 100644 > --- a/include/drm/drm_plane.h > +++ b/include/drm/drm_plane.h > @@ -249,9 +249,9 @@ struct drm_plane_funcs { > * Duplicate the current atomic state for this plane and return it. > * The core and helpers gurantee that any atomic state duplicated with "guarantee" > * 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,8 +470,8 @@ 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 > + * Protects modeset plane state, together with the &drm_crtc.mutex of > + * CRTC this plane is linked to (when active, getting actived or getting "activated" > * 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 > * > -- > 2.11.0 > _______________________________________________ dri-devel mailing list dri-devel@xxxxxxxxxxxxxxxxxxxxx https://lists.freedesktop.org/mailman/listinfo/dri-devel