Re: [PATCH 05/15] drm/core: Use recommened kerneldoc for struct member refs

[Gustavo Padovan <gustavo@padovan.org>]

Hi Daniel,

2017-01-25 Daniel Vetter <daniel.vetter@ffwll.ch>:

> 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@linux.intel.com>
> Cc: Chris Wilson <chris@chris-wilson.co.uk>
> Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
> ---
>  drivers/gpu/drm/drm_auth.c     |  4 ++--
>  drivers/gpu/drm/drm_drv.c      |  8 ++++----
>  drivers/gpu/drm/drm_fops.c     | 11 ++++++-----
>  drivers/gpu/drm/drm_irq.c      | 10 +++++-----
>  drivers/gpu/drm/drm_pci.c      |  2 +-
>  drivers/gpu/drm/drm_platform.c |  2 +-
>  drivers/gpu/drm/drm_sysfs.c    |  2 +-
>  include/drm/drm_auth.h         | 12 ++++++------
>  include/drm/drm_drv.h          |  2 +-
>  include/drm/drm_irq.h          |  4 ++--
>  10 files changed, 29 insertions(+), 28 deletions(-)
> 
> diff --git a/drivers/gpu/drm/drm_auth.c b/drivers/gpu/drm/drm_auth.c
> index 860cfe124c2a..7ff697389d74 100644
> --- a/drivers/gpu/drm/drm_auth.c
> +++ b/drivers/gpu/drm/drm_auth.c
> @@ -40,8 +40,8 @@
>   * least once successfully became the device master (either through the
>   * SET_MASTER IOCTL, or implicitly through opening the primary device node when
>   * no one else is the current master that time) there exists one &drm_master.
> - * This is noted in the is_master member of &drm_file. All other clients have
> - * just a pointer to the &drm_master they are associated with.
> + * This is noted in &drm_file.is_master. All other clients have just a pointer
> + * to the &drm_master they are associated with.
>   *
>   * In addition only one &drm_master can be the current master for a &drm_device.
>   * It can be switched through the DROP_MASTER and SET_MASTER IOCTL, or
> diff --git a/drivers/gpu/drm/drm_drv.c b/drivers/gpu/drm/drm_drv.c
> index 72116978ec06..242f67c08982 100644
> --- a/drivers/gpu/drm/drm_drv.c
> +++ b/drivers/gpu/drm/drm_drv.c
> @@ -309,7 +309,7 @@ void drm_minor_release(struct drm_minor *minor)
>   * userspace the device instance can be published using drm_dev_register().
>   *
>   * There is also deprecated support for initalizing device instances using
> - * bus-specific helpers and the ->load() callback. But due to
> + * bus-specific helpers and the &drm_driver.load callback. But due to
>   * backwards-compatibility needs the device instance have to be published too
>   * early, which requires unpretty global locking to make safe and is therefore
>   * only support for existing drivers not yet converted to the new scheme.
> @@ -720,9 +720,9 @@ static void remove_compat_control_link(struct drm_device *dev)
>   * Never call this twice on any device!
>   *
>   * NOTE: To ensure backward compatibility with existing drivers method this
> - * function calls the ->load() method after registering the device nodes,
> - * creating race conditions. Usage of the ->load() methods is therefore
> - * deprecated, drivers must perform all initialization before calling
> + * function calls the &drm_driver.load method after registering the device
> + * nodes, creating race conditions. Usage of the &drm_driver.load methods is
> + * therefore deprecated, drivers must perform all initialization before calling
>   * drm_dev_register().
>   *
>   * RETURNS:
> diff --git a/drivers/gpu/drm/drm_fops.c b/drivers/gpu/drm/drm_fops.c
> index e22645375e60..afdf5b147f39 100644
> --- a/drivers/gpu/drm/drm_fops.c
> +++ b/drivers/gpu/drm/drm_fops.c
> @@ -580,7 +580,7 @@ EXPORT_SYMBOL(drm_poll);
>   * kmalloc and @p must be the first member element.
>   *
>   * This is the locked version of drm_event_reserve_init() for callers which
> - * already hold dev->event_lock.
> + * already hold &drm_device.event_lock.
>   *
>   * RETURNS:
>   *
> @@ -621,7 +621,7 @@ EXPORT_SYMBOL(drm_event_reserve_init_locked);
>   * If callers embedded @p into a larger structure it must be allocated with
>   * kmalloc and @p must be the first member element.
>   *
> - * Callers which already hold dev->event_lock should use
> + * Callers which already hold &drm_device.event_lock should use
>   * drm_event_reserve_init_locked() instead.
>   *
>   * RETURNS:
> @@ -677,7 +677,7 @@ EXPORT_SYMBOL(drm_event_cancel_free);
>   *
>   * This function sends the event @e, initialized with drm_event_reserve_init(),
>   * to its associated userspace DRM file. Callers must already hold
> - * dev->event_lock, see drm_send_event() for the unlocked version.
> + * &drm_device.event_lock, see drm_send_event() for the unlocked version.
>   *
>   * Note that the core will take care of unlinking and disarming events when the
>   * corresponding DRM file is closed. Drivers need not worry about whether the
> @@ -717,8 +717,9 @@ EXPORT_SYMBOL(drm_send_event_locked);
>   * @e: DRM event to deliver
>   *
>   * This function sends the event @e, initialized with drm_event_reserve_init(),
> - * to its associated userspace DRM file. This function acquires dev->event_lock,
> - * see drm_send_event_locked() for callers which already hold this lock.
> + * to its associated userspace DRM file. This function acquires
> + * &drm_device.event_lock, see drm_send_event_locked() for callers which already
> + * hold this lock.
>   *
>   * Note that the core will take care of unlinking and disarming events when the
>   * corresponding DRM file is closed. Drivers need not worry about whether the
> diff --git a/drivers/gpu/drm/drm_irq.c b/drivers/gpu/drm/drm_irq.c
> index 88c69e71102e..1c4da043eeda 100644
> --- a/drivers/gpu/drm/drm_irq.c
> +++ b/drivers/gpu/drm/drm_irq.c
> @@ -95,7 +95,7 @@ static void store_vblank(struct drm_device *dev, unsigned int pipe,
>   *
>   * Only to be called from drm_crtc_vblank_on().
>   *
> - * Note: caller must hold dev->vbl_lock since this reads & writes
> + * Note: caller must hold &drm_device.vbl_lock since this reads & writes
>   * device vblank fields.
>   */
>  static void drm_reset_vblank_timestamp(struct drm_device *dev, unsigned int pipe)
> @@ -142,7 +142,7 @@ static void drm_reset_vblank_timestamp(struct drm_device *dev, unsigned int pipe
>   * Only necessary when going from off->on, to account for frames we
>   * didn't get an interrupt for.
>   *
> - * Note: caller must hold dev->vbl_lock since this reads & writes
> + * Note: caller must hold &drm_device.vbl_lock since this reads & writes
>   * device vblank fields.
>   */
>  static void drm_update_vblank_count(struct drm_device *dev, unsigned int pipe,
> @@ -449,7 +449,7 @@ static void drm_irq_vgaarb_nokms(void *cookie, bool state)
>   *
>   * This is the simplified helper interface provided for drivers with no special
>   * needs. Drivers which need to install interrupt handlers for multiple
> - * interrupts must instead set drm_device->irq_enabled to signal the DRM core
> + * interrupts must instead set &drm_device.irq_enabled to signal the DRM core
>   * that vblank interrupts are available.
>   *
>   * Returns:
> @@ -519,7 +519,7 @@ EXPORT_SYMBOL(drm_irq_install);
>   * Calls the driver's irq_uninstall() function and unregisters the IRQ handler.
>   * This should only be called by drivers which used drm_irq_install() to set up
>   * their interrupt handler. Other drivers must only reset
> - * drm_device->irq_enabled to false.
> + * &drm_device.irq_enabled to false.
>   *
>   * Note that for kernel modesetting drivers it is a bug if this function fails.
>   * The sanity checks are only to catch buggy user modesetting drivers which call
> @@ -982,7 +982,7 @@ static void send_vblank_event(struct drm_device *dev,
>   * period. This helper function implements exactly the required vblank arming
>   * behaviour.
>   *
> - * NOTE: Drivers using this to send out the event in &struct drm_crtc_state
> + * NOTE: Drivers using this to send out the &struct drm_crtc_state.event

&drm_crtc_state.event?

>   * as part of an atomic commit must ensure that the next vblank happens at
>   * exactly the same time as the atomic commit is committed to the hardware. This
>   * function itself does **not** protect again the next vblank interrupt racing
> diff --git a/drivers/gpu/drm/drm_pci.c b/drivers/gpu/drm/drm_pci.c
> index dc358f860aea..50c732a95b5a 100644
> --- a/drivers/gpu/drm/drm_pci.c
> +++ b/drivers/gpu/drm/drm_pci.c
> @@ -223,7 +223,7 @@ void drm_pci_agp_destroy(struct drm_device *dev)
>   * Try and register, if we fail to register, backout previous work.
>   *
>   * NOTE: This function is deprecated, please use drm_dev_alloc() and
> - * drm_dev_register() instead and remove your ->load() callback.
> + * drm_dev_register() instead and remove your &drm_driver.load() callback.

&drm_driver.load?

>   *
>   * Return: 0 on success or a negative error code on failure.
>   */
> diff --git a/drivers/gpu/drm/drm_platform.c b/drivers/gpu/drm/drm_platform.c
> index 7af3005a030c..3b34c3717c4d 100644
> --- a/drivers/gpu/drm/drm_platform.c
> +++ b/drivers/gpu/drm/drm_platform.c
> @@ -74,7 +74,7 @@ static int drm_get_platform_dev(struct platform_device *platdev,
>   * .load() function.
>   *
>   * NOTE: This function is deprecated, please use drm_dev_alloc() and
> - * drm_dev_register() instead and remove your ->load() callback.
> + * drm_dev_register() instead and remove your &drm_driver.load() callback.

&drm_driver.load?

Otherwise looks good:

Reviewed-by: Gustavo Padovan <gustavo.padovan@collabora.com>
_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx