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 --- drivers/gpu/drm/drm_atomic.c | 78 ++++++++++++++++++------------------- 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 | 12 +++--- drivers/gpu/drm/drm_modeset_lock.c | 10 ++--- drivers/gpu/drm/drm_plane.c | 2 +- drivers/gpu/drm/drm_property.c | 4 +- 11 files changed, 70 insertions(+), 74 deletions(-) (limited to 'drivers/gpu/drm') diff --git a/drivers/gpu/drm/drm_atomic.c b/drivers/gpu/drm/drm_atomic.c index 6414bcf7f41b..7fd88a09304b 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 @@ -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. * 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 @@ 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 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..28a0108a1ab8 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,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. * 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..7fc070f3e49e 100644 --- a/drivers/gpu/drm/drm_property.c +++ b/drivers/gpu/drm/drm_property.c @@ -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 -- cgit