Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit ef40cbf9 authored by Daniel Vetter's avatar Daniel Vetter
Browse files

drm/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 Gustavo.

Cc: Jani Nikula <jani.nikula@linux.intel.com>
Cc: Chris Wilson <chris@chris-wilson.co.uk>
Reviewed-by: default avatarGustavo Padovan <gustavo.padovan@collabora.com>
Signed-off-by: default avatarDaniel Vetter <daniel.vetter@intel.com>
Link: http://patchwork.freedesktop.org/patch/msgid/20170125062657.19270-6-daniel.vetter@ffwll.ch
parent 940eba2d

drivers/gpu/drm/drm_auth.c

+2 −2
Original line number Diff line number Diff line
@@ -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

drivers/gpu/drm/drm_drv.c

+4 −4
Original line number Diff line number Diff line
@@ -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.
@@ -718,9 +718,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:

drivers/gpu/drm/drm_fops.c

+6 −5
Original line number Diff line number Diff line
@@ -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

drivers/gpu/drm/drm_irq.c

+9 −10
Original line number Diff line number Diff line
@@ -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,12 +982,11 @@ 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

 * 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

 * with either this function call or the atomic commit operation. A possible

 * sequence could be:

 * NOTE: Drivers using this to send out the &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 with either this

 * function call or the atomic commit operation. A possible sequence could be:

 *

 * 1. Driver commits new hardware state into vblank-synchronized registers.

 * 2. A vblank happens, committing the hardware state. Also the corresponding

drivers/gpu/drm/drm_pci.c

+1 −1
Original line number Diff line number Diff line
@@ -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.

 *

 * Return: 0 on success or a negative error code on failure.

 */