Commit ef40cbf9 authored by Daniel Vetter's avatar Daniel Vetter

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
...@@ -40,8 +40,8 @@ ...@@ -40,8 +40,8 @@
* least once successfully became the device master (either through the * least once successfully became the device master (either through the
* SET_MASTER IOCTL, or implicitly through opening the primary device node when * 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. * 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 * This is noted in &drm_file.is_master. All other clients have just a pointer
* just a pointer to the &drm_master they are associated with. * to the &drm_master they are associated with.
* *
* In addition only one &drm_master can be the current master for a &drm_device. * 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 * It can be switched through the DROP_MASTER and SET_MASTER IOCTL, or
......
...@@ -309,7 +309,7 @@ void drm_minor_release(struct drm_minor *minor) ...@@ -309,7 +309,7 @@ void drm_minor_release(struct drm_minor *minor)
* userspace the device instance can be published using drm_dev_register(). * userspace the device instance can be published using drm_dev_register().
* *
* There is also deprecated support for initalizing device instances using * 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 * backwards-compatibility needs the device instance have to be published too
* early, which requires unpretty global locking to make safe and is therefore * early, which requires unpretty global locking to make safe and is therefore
* only support for existing drivers not yet converted to the new scheme. * 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) ...@@ -718,9 +718,9 @@ static void remove_compat_control_link(struct drm_device *dev)
* Never call this twice on any device! * Never call this twice on any device!
* *
* NOTE: To ensure backward compatibility with existing drivers method this * NOTE: To ensure backward compatibility with existing drivers method this
* function calls the ->load() method after registering the device nodes, * function calls the &drm_driver.load method after registering the device
* creating race conditions. Usage of the ->load() methods is therefore * nodes, creating race conditions. Usage of the &drm_driver.load methods is
* deprecated, drivers must perform all initialization before calling * therefore deprecated, drivers must perform all initialization before calling
* drm_dev_register(). * drm_dev_register().
* *
* RETURNS: * RETURNS:
......
...@@ -580,7 +580,7 @@ EXPORT_SYMBOL(drm_poll); ...@@ -580,7 +580,7 @@ EXPORT_SYMBOL(drm_poll);
* kmalloc and @p must be the first member element. * kmalloc and @p must be the first member element.
* *
* This is the locked version of drm_event_reserve_init() for callers which * 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: * RETURNS:
* *
...@@ -621,7 +621,7 @@ EXPORT_SYMBOL(drm_event_reserve_init_locked); ...@@ -621,7 +621,7 @@ EXPORT_SYMBOL(drm_event_reserve_init_locked);
* If callers embedded @p into a larger structure it must be allocated with * If callers embedded @p into a larger structure it must be allocated with
* kmalloc and @p must be the first member element. * 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. * drm_event_reserve_init_locked() instead.
* *
* RETURNS: * RETURNS:
...@@ -677,7 +677,7 @@ EXPORT_SYMBOL(drm_event_cancel_free); ...@@ -677,7 +677,7 @@ EXPORT_SYMBOL(drm_event_cancel_free);
* *
* This function sends the event @e, initialized with drm_event_reserve_init(), * This function sends the event @e, initialized with drm_event_reserve_init(),
* to its associated userspace DRM file. Callers must already hold * 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 * 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 * corresponding DRM file is closed. Drivers need not worry about whether the
...@@ -717,8 +717,9 @@ EXPORT_SYMBOL(drm_send_event_locked); ...@@ -717,8 +717,9 @@ EXPORT_SYMBOL(drm_send_event_locked);
* @e: DRM event to deliver * @e: DRM event to deliver
* *
* This function sends the event @e, initialized with drm_event_reserve_init(), * This function sends the event @e, initialized with drm_event_reserve_init(),
* to its associated userspace DRM file. This function acquires dev->event_lock, * to its associated userspace DRM file. This function acquires
* see drm_send_event_locked() for callers which already hold this lock. * &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 * 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 * corresponding DRM file is closed. Drivers need not worry about whether the
......
...@@ -95,7 +95,7 @@ static void store_vblank(struct drm_device *dev, unsigned int pipe, ...@@ -95,7 +95,7 @@ static void store_vblank(struct drm_device *dev, unsigned int pipe,
* *
* Only to be called from drm_crtc_vblank_on(). * 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. * device vblank fields.
*/ */
static void drm_reset_vblank_timestamp(struct drm_device *dev, unsigned int pipe) 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 ...@@ -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 * Only necessary when going from off->on, to account for frames we
* didn't get an interrupt for. * 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. * device vblank fields.
*/ */
static void drm_update_vblank_count(struct drm_device *dev, unsigned int pipe, 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) ...@@ -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 * This is the simplified helper interface provided for drivers with no special
* needs. Drivers which need to install interrupt handlers for multiple * 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. * that vblank interrupts are available.
* *
* Returns: * Returns:
...@@ -519,7 +519,7 @@ EXPORT_SYMBOL(drm_irq_install); ...@@ -519,7 +519,7 @@ EXPORT_SYMBOL(drm_irq_install);
* Calls the driver's irq_uninstall() function and unregisters the IRQ handler. * 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 * This should only be called by drivers which used drm_irq_install() to set up
* their interrupt handler. Other drivers must only reset * 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. * 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 * 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, ...@@ -982,12 +982,11 @@ static void send_vblank_event(struct drm_device *dev,
* period. This helper function implements exactly the required vblank arming * period. This helper function implements exactly the required vblank arming
* behaviour. * behaviour.
* *
* NOTE: Drivers using this to send out the event in &struct drm_crtc_state * NOTE: Drivers using this to send out the &drm_crtc_state.event as part of an
* as part of an atomic commit must ensure that the next vblank happens at * atomic commit must ensure that the next vblank happens at exactly the same
* exactly the same time as the atomic commit is committed to the hardware. This * time as the atomic commit is committed to the hardware. This function itself
* function itself does **not** protect again the next vblank interrupt racing * does **not** protect again the next vblank interrupt racing with either this
* with either this function call or the atomic commit operation. A possible * function call or the atomic commit operation. A possible sequence could be:
* sequence could be:
* *
* 1. Driver commits new hardware state into vblank-synchronized registers. * 1. Driver commits new hardware state into vblank-synchronized registers.
* 2. A vblank happens, committing the hardware state. Also the corresponding * 2. A vblank happens, committing the hardware state. Also the corresponding
......
...@@ -223,7 +223,7 @@ void drm_pci_agp_destroy(struct drm_device *dev) ...@@ -223,7 +223,7 @@ void drm_pci_agp_destroy(struct drm_device *dev)
* Try and register, if we fail to register, backout previous work. * Try and register, if we fail to register, backout previous work.
* *
* NOTE: This function is deprecated, please use drm_dev_alloc() and * 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. * Return: 0 on success or a negative error code on failure.
*/ */
......
...@@ -74,7 +74,7 @@ static int drm_get_platform_dev(struct platform_device *platdev, ...@@ -74,7 +74,7 @@ static int drm_get_platform_dev(struct platform_device *platdev,
* .load() function. * .load() function.
* *
* NOTE: This function is deprecated, please use drm_dev_alloc() and * 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. * Return: 0 on success or a negative error code on failure.
*/ */
......
...@@ -255,7 +255,7 @@ static const struct attribute_group *connector_dev_groups[] = { ...@@ -255,7 +255,7 @@ static const struct attribute_group *connector_dev_groups[] = {
* @connector: connector to add * @connector: connector to add
* *
* Create a connector device in sysfs, along with its associated connector * Create a connector device in sysfs, along with its associated connector
* properties (so far, connection status, dpms, mode list & edid) and * properties (so far, connection status, dpms, mode list and edid) and
* generate a hotplug event so userspace knows there's a new connector * generate a hotplug event so userspace knows there's a new connector
* available. * available.
*/ */
......
...@@ -43,18 +43,18 @@ struct drm_master { ...@@ -43,18 +43,18 @@ struct drm_master {
struct kref refcount; struct kref refcount;
struct drm_device *dev; struct drm_device *dev;
/** /**
* @unique: Unique identifier: e.g. busid. Protected by struct * @unique: Unique identifier: e.g. busid. Protected by
* &drm_device master_mutex. * &drm_device.master_mutex.
*/ */
char *unique; char *unique;
/** /**
* @unique_len: Length of unique field. Protected by &struct drm_device * @unique_len: Length of unique field. Protected by
* master_mutex. * &drm_device.master_mutex.
*/ */
int unique_len; int unique_len;
/** /**
* @magic_map: Map of used authentication tokens. Protected by struct * @magic_map: Map of used authentication tokens. Protected by
* &drm_device master_mutex. * &drm_device.master_mutex.
*/ */
struct idr magic_map; struct idr magic_map;
struct drm_lock_data lock; struct drm_lock_data lock;
......
...@@ -314,7 +314,7 @@ struct drm_driver { ...@@ -314,7 +314,7 @@ struct drm_driver {
/** /**
* @gem_free_object_unlocked: deconstructor for drm_gem_objects * @gem_free_object_unlocked: deconstructor for drm_gem_objects
* *
* This is for drivers which are not encumbered with dev->struct_mutex * This is for drivers which are not encumbered with &drm_device.struct_mutex
* legacy locking schemes. Use this hook instead of @gem_free_object. * legacy locking schemes. Use this hook instead of @gem_free_object.
*/ */
void (*gem_free_object_unlocked) (struct drm_gem_object *obj); void (*gem_free_object_unlocked) (struct drm_gem_object *obj);
......
...@@ -67,7 +67,7 @@ struct drm_vblank_crtc { ...@@ -67,7 +67,7 @@ struct drm_vblank_crtc {
* @disable_timer: Disable timer for the delayed vblank disabling * @disable_timer: Disable timer for the delayed vblank disabling
* hysteresis logic. Vblank disabling is controlled through the * hysteresis logic. Vblank disabling is controlled through the
* drm_vblank_offdelay module option and the setting of the * drm_vblank_offdelay module option and the setting of the
* max_vblank_count value in the &drm_device structure. * &drm_device.max_vblank_count value.
*/ */
struct timer_list disable_timer; struct timer_list disable_timer;
...@@ -92,7 +92,7 @@ struct drm_vblank_crtc { ...@@ -92,7 +92,7 @@ struct drm_vblank_crtc {
*/ */
atomic_t refcount; /* number of users of vblank interruptsper crtc */ atomic_t refcount; /* number of users of vblank interruptsper crtc */
/** /**
* @last: Protected by dev->vbl_lock, used for wraparound handling. * @last: Protected by &drm_device.vbl_lock, used for wraparound handling.
*/ */
u32 last; u32 last;
/** /**
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment