Merge remote-tracking branch 'drm-misc/topic/drm-misc'
authorStephen Rothwell <sfr@canb.auug.org.au>
Thu, 5 Nov 2015 01:12:45 +0000 (12:12 +1100)
committerStephen Rothwell <sfr@canb.auug.org.au>
Thu, 5 Nov 2015 01:12:45 +0000 (12:12 +1100)
12 files changed:
Documentation/DocBook/gpu.tmpl
drivers/gpu/drm/drm_gem.c
drivers/gpu/drm/imx/Kconfig
drivers/gpu/drm/imx/imx-drm-core.c
drivers/gpu/drm/sti/Kconfig
drivers/gpu/drm/sti/sti_drv.c
drivers/gpu/drm/tegra/Kconfig
drivers/gpu/drm/tegra/drm.c
drivers/gpu/drm/tegra/drm.h
drivers/gpu/drm/tegra/fb.c
include/drm/drm_dp_helper.h
include/drm/drm_gem.h

index 201dcd3..944e65a 100644 (file)
@@ -615,18 +615,6 @@ char *date;</synopsis>
           <function>drm_gem_object_init</function>. Storage for private GEM
           objects must be managed by drivers.
         </para>
-        <para>
-          Drivers that do not need to extend GEM objects with private information
-          can call the <function>drm_gem_object_alloc</function> function to
-          allocate and initialize a struct <structname>drm_gem_object</structname>
-          instance. The GEM core will call the optional driver
-          <methodname>gem_init_object</methodname> operation after initializing
-          the GEM object with <function>drm_gem_object_init</function>.
-          <synopsis>int (*gem_init_object) (struct drm_gem_object *obj);</synopsis>
-        </para>
-        <para>
-          No alloc-and-init function exists for private GEM objects.
-        </para>
       </sect3>
       <sect3>
         <title>GEM Objects Lifetime</title>
@@ -635,10 +623,10 @@ char *date;</synopsis>
           acquired and release by <function>calling drm_gem_object_reference</function>
           and <function>drm_gem_object_unreference</function> respectively. The
           caller must hold the <structname>drm_device</structname>
-          <structfield>struct_mutex</structfield> lock. As a convenience, GEM
-          provides the <function>drm_gem_object_reference_unlocked</function> and
-          <function>drm_gem_object_unreference_unlocked</function> functions that
-          can be called without holding the lock.
+         <structfield>struct_mutex</structfield> lock when calling
+         <function>drm_gem_object_reference</function>. As a convenience, GEM
+         provides <function>drm_gem_object_unreference_unlocked</function>
+         functions that can be called without holding the lock.
         </para>
         <para>
           When the last reference to a GEM object is released the GEM core calls
@@ -649,15 +637,9 @@ char *date;</synopsis>
         </para>
         <para>
           <synopsis>void (*gem_free_object) (struct drm_gem_object *obj);</synopsis>
-          Drivers are responsible for freeing all GEM object resources, including
-          the resources created by the GEM core. If an mmap offset has been
-          created for the object (in which case
-          <structname>drm_gem_object</structname>::<structfield>map_list</structfield>::<structfield>map</structfield>
-          is not NULL) it must be freed by a call to
-          <function>drm_gem_free_mmap_offset</function>. The shmfs backing store
-          must be released by calling <function>drm_gem_object_release</function>
-          (that function can safely be called if no shmfs backing store has been
-          created).
+          Drivers are responsible for freeing all GEM object resources. This includes
+          the resources created by the GEM core, which need to be released with
+          <function>drm_gem_object_release</function>.
         </para>
       </sect3>
       <sect3>
@@ -740,17 +722,10 @@ char *date;</synopsis>
           DRM identifies the GEM object to be mapped by a fake offset passed
           through the mmap offset argument. Prior to being mapped, a GEM object
           must thus be associated with a fake offset. To do so, drivers must call
-          <function>drm_gem_create_mmap_offset</function> on the object. The
-          function allocates a fake offset range from a pool and stores the
-          offset divided by PAGE_SIZE in
-          <literal>obj-&gt;map_list.hash.key</literal>. Care must be taken not to
-          call <function>drm_gem_create_mmap_offset</function> if a fake offset
-          has already been allocated for the object. This can be tested by
-          <literal>obj-&gt;map_list.map</literal> being non-NULL.
+          <function>drm_gem_create_mmap_offset</function> on the object.
         </para>
         <para>
           Once allocated, the fake offset value
-          (<literal>obj-&gt;map_list.hash.key &lt;&lt; PAGE_SHIFT</literal>)
           must be passed to the application in a driver-specific way and can then
           be used as the mmap offset argument.
         </para>
@@ -836,10 +811,11 @@ char *date;</synopsis>
           abstracted from the client in libdrm.
         </para>
       </sect3>
-      <sect3>
-        <title>GEM Function Reference</title>
+    </sect2>
+    <sect2>
+      <title>GEM Function Reference</title>
 !Edrivers/gpu/drm/drm_gem.c
-      </sect3>
+!Iinclude/drm/drm_gem.h
     </sect2>
     <sect2>
       <title>VMA Offset Manager</title>
index 64353d4..abeb9af 100644 (file)
@@ -244,8 +244,9 @@ drm_gem_object_handle_unreference_unlocked(struct drm_gem_object *obj)
  * @filp: drm file-private structure to use for the handle look up
  * @handle: userspace handle to delete
  *
- * Removes the GEM handle from the @filp lookup table and if this is the last
- * handle also cleans up linked resources like GEM names.
+ * Removes the GEM handle from the @filp lookup table which has been added with
+ * drm_gem_handle_create(). If this is the last handle also cleans up linked
+ * resources like GEM names.
  */
 int
 drm_gem_handle_delete(struct drm_file *filp, u32 handle)
@@ -314,6 +315,10 @@ EXPORT_SYMBOL(drm_gem_dumb_destroy);
  * This expects the dev->object_name_lock to be held already and will drop it
  * before returning. Used to avoid races in establishing new handles when
  * importing an object from either an flink name or a dma-buf.
+ *
+ * Handles must be release again through drm_gem_handle_delete(). This is done
+ * when userspace closes @file_priv for all attached handles, or through the
+ * GEM_CLOSE ioctl for individual handles.
  */
 int
 drm_gem_handle_create_tail(struct drm_file *file_priv,
@@ -541,7 +546,17 @@ void drm_gem_put_pages(struct drm_gem_object *obj, struct page **pages,
 }
 EXPORT_SYMBOL(drm_gem_put_pages);
 
-/** Returns a reference to the object named by the handle. */
+/**
+ * drm_gem_object_lookup - look up a GEM object from it's handle
+ * @dev: DRM device
+ * @filp: DRM file private date
+ * @handle: userspace handle
+ *
+ * Returns:
+ *
+ * A reference to the object named by the handle if such exists on @filp, NULL
+ * otherwise.
+ */
 struct drm_gem_object *
 drm_gem_object_lookup(struct drm_device *dev, struct drm_file *filp,
                      u32 handle)
@@ -774,6 +789,13 @@ drm_gem_object_free(struct kref *kref)
 }
 EXPORT_SYMBOL(drm_gem_object_free);
 
+/**
+ * drm_gem_vm_open - vma->ops->open implementation for GEM
+ * @vma: VM area structure
+ *
+ * This function implements the #vm_operations_struct open() callback for GEM
+ * drivers. This must be used together with drm_gem_vm_close().
+ */
 void drm_gem_vm_open(struct vm_area_struct *vma)
 {
        struct drm_gem_object *obj = vma->vm_private_data;
@@ -782,6 +804,13 @@ void drm_gem_vm_open(struct vm_area_struct *vma)
 }
 EXPORT_SYMBOL(drm_gem_vm_open);
 
+/**
+ * drm_gem_vm_close - vma->ops->close implementation for GEM
+ * @vma: VM area structure
+ *
+ * This function implements the #vm_operations_struct close() callback for GEM
+ * drivers. This must be used together with drm_gem_vm_open().
+ */
 void drm_gem_vm_close(struct vm_area_struct *vma)
 {
        struct drm_gem_object *obj = vma->vm_private_data;
index 2b81a41..35ca4f0 100644 (file)
@@ -10,15 +10,6 @@ config DRM_IMX
        help
          enable i.MX graphics support
 
-config DRM_IMX_FB_HELPER
-       tristate "provide legacy framebuffer /dev/fb0"
-       select DRM_KMS_CMA_HELPER
-       depends on DRM_IMX
-       help
-         The DRM framework can provide a legacy /dev/fb0 framebuffer
-         for your device. This is necessary to get a framebuffer console
-         and also for applications using the legacy framebuffer API
-
 config DRM_IMX_PARALLEL_DISPLAY
        tristate "Support for parallel displays"
        select DRM_PANEL
index 64f16ea..6faa735 100644 (file)
@@ -49,8 +49,10 @@ struct imx_drm_crtc {
        struct imx_drm_crtc_helper_funcs        imx_drm_helper_funcs;
 };
 
+#if IS_ENABLED(CONFIG_DRM_FBDEV_EMULATION)
 static int legacyfb_depth = 16;
 module_param(legacyfb_depth, int, 0444);
+#endif
 
 int imx_drm_crtc_id(struct imx_drm_crtc *crtc)
 {
@@ -60,26 +62,20 @@ EXPORT_SYMBOL_GPL(imx_drm_crtc_id);
 
 static void imx_drm_driver_lastclose(struct drm_device *drm)
 {
-#if IS_ENABLED(CONFIG_DRM_IMX_FB_HELPER)
        struct imx_drm_device *imxdrm = drm->dev_private;
 
        if (imxdrm->fbhelper)
                drm_fbdev_cma_restore_mode(imxdrm->fbhelper);
-#endif
 }
 
 static int imx_drm_driver_unload(struct drm_device *drm)
 {
-#if IS_ENABLED(CONFIG_DRM_IMX_FB_HELPER)
        struct imx_drm_device *imxdrm = drm->dev_private;
-#endif
 
        drm_kms_helper_poll_fini(drm);
 
-#if IS_ENABLED(CONFIG_DRM_IMX_FB_HELPER)
        if (imxdrm->fbhelper)
                drm_fbdev_cma_fini(imxdrm->fbhelper);
-#endif
 
        component_unbind_all(drm->dev, drm);
 
@@ -215,11 +211,9 @@ EXPORT_SYMBOL_GPL(imx_drm_encoder_destroy);
 
 static void imx_drm_output_poll_changed(struct drm_device *drm)
 {
-#if IS_ENABLED(CONFIG_DRM_IMX_FB_HELPER)
        struct imx_drm_device *imxdrm = drm->dev_private;
 
        drm_fbdev_cma_hotplug_event(imxdrm->fbhelper);
-#endif
 }
 
 static struct drm_mode_config_funcs imx_drm_mode_config_funcs = {
@@ -308,7 +302,7 @@ static int imx_drm_driver_load(struct drm_device *drm, unsigned long flags)
         * The fb helper takes copies of key hardware information, so the
         * crtcs/connectors/encoders must not change after this point.
         */
-#if IS_ENABLED(CONFIG_DRM_IMX_FB_HELPER)
+#if IS_ENABLED(CONFIG_DRM_FBDEV_EMULATION)
        if (legacyfb_depth != 16 && legacyfb_depth != 32) {
                dev_warn(drm->dev, "Invalid legacyfb_depth.  Defaulting to 16bpp\n");
                legacyfb_depth = 16;
index fbccc10..e3aa5af 100644 (file)
@@ -9,9 +9,3 @@ config DRM_STI
        select FW_LOADER_USER_HELPER_FALLBACK
        help
          Choose this option to enable DRM on STM stiH41x chipset
-
-config DRM_STI_FBDEV
-       bool "DRM frame buffer device for STMicroelectronics SoC stiH41x Serie"
-       depends on DRM_STI
-       help
-         Choose this option to enable FBDEV on top of DRM for STM stiH41x chipset
index f846996..1b2db6c 100644 (file)
@@ -160,7 +160,7 @@ static int sti_load(struct drm_device *dev, unsigned long flags)
 
        drm_mode_config_reset(dev);
 
-#ifdef CONFIG_DRM_STI_FBDEV
+#ifdef CONFIG_DRM_FBDEV_EMULATION
        drm_fbdev_cma_init(dev, 32,
                           dev->mode_config.num_crtc,
                           dev->mode_config.num_connector);
index 74d9d62..63ebb15 100644 (file)
@@ -16,18 +16,6 @@ config DRM_TEGRA
 
 if DRM_TEGRA
 
-config DRM_TEGRA_FBDEV
-       bool "Enable legacy fbdev support"
-       select DRM_KMS_FB_HELPER
-       select FB_SYS_FILLRECT
-       select FB_SYS_COPYAREA
-       select FB_SYS_IMAGEBLIT
-       default y
-       help
-         Choose this option if you have a need for the legacy fbdev support.
-         Note that this support also provides the Linux console on top of
-         the Tegra modesetting driver.
-
 config DRM_TEGRA_DEBUG
        bool "NVIDIA Tegra DRM debug support"
        help
index 159ef51..e0f8277 100644 (file)
@@ -106,7 +106,7 @@ static int tegra_atomic_commit(struct drm_device *drm,
 
 static const struct drm_mode_config_funcs tegra_drm_mode_funcs = {
        .fb_create = tegra_fb_create,
-#ifdef CONFIG_DRM_TEGRA_FBDEV
+#ifdef CONFIG_DRM_FBDEV_EMULATION
        .output_poll_changed = tegra_fb_output_poll_changed,
 #endif
        .atomic_check = drm_atomic_helper_check,
@@ -260,7 +260,7 @@ static void tegra_drm_context_free(struct tegra_drm_context *context)
 
 static void tegra_drm_lastclose(struct drm_device *drm)
 {
-#ifdef CONFIG_DRM_TEGRA_FBDEV
+#ifdef CONFIG_DRM_FBDEV_EMULATION
        struct tegra_drm *tegra = drm->dev_private;
 
        tegra_fbdev_restore_mode(tegra->fbdev);
index ec49275..942cad9 100644 (file)
@@ -30,7 +30,7 @@ struct tegra_fb {
        unsigned int num_planes;
 };
 
-#ifdef CONFIG_DRM_TEGRA_FBDEV
+#ifdef CONFIG_DRM_FBDEV_EMULATION
 struct tegra_fbdev {
        struct drm_fb_helper base;
        struct tegra_fb *fb;
@@ -46,7 +46,7 @@ struct tegra_drm {
        struct mutex clients_lock;
        struct list_head clients;
 
-#ifdef CONFIG_DRM_TEGRA_FBDEV
+#ifdef CONFIG_DRM_FBDEV_EMULATION
        struct tegra_fbdev *fbdev;
 #endif
 
@@ -273,7 +273,7 @@ int tegra_drm_fb_prepare(struct drm_device *drm);
 void tegra_drm_fb_free(struct drm_device *drm);
 int tegra_drm_fb_init(struct drm_device *drm);
 void tegra_drm_fb_exit(struct drm_device *drm);
-#ifdef CONFIG_DRM_TEGRA_FBDEV
+#ifdef CONFIG_DRM_FBDEV_EMULATION
 void tegra_fbdev_restore_mode(struct tegra_fbdev *fbdev);
 void tegra_fb_output_poll_changed(struct drm_device *drm);
 #endif
index 1004075..bec07d9 100644 (file)
@@ -18,7 +18,7 @@ static inline struct tegra_fb *to_tegra_fb(struct drm_framebuffer *fb)
        return container_of(fb, struct tegra_fb, base);
 }
 
-#ifdef CONFIG_DRM_TEGRA_FBDEV
+#ifdef CONFIG_DRM_FBDEV_EMULATION
 static inline struct tegra_fbdev *to_tegra_fbdev(struct drm_fb_helper *helper)
 {
        return container_of(helper, struct tegra_fbdev, base);
@@ -181,7 +181,7 @@ unreference:
        return ERR_PTR(err);
 }
 
-#ifdef CONFIG_DRM_TEGRA_FBDEV
+#ifdef CONFIG_DRM_FBDEV_EMULATION
 static struct fb_ops tegra_fb_ops = {
        .owner = THIS_MODULE,
        .fb_fillrect = drm_fb_helper_sys_fillrect,
@@ -370,7 +370,7 @@ void tegra_fb_output_poll_changed(struct drm_device *drm)
 
 int tegra_drm_fb_prepare(struct drm_device *drm)
 {
-#ifdef CONFIG_DRM_TEGRA_FBDEV
+#ifdef CONFIG_DRM_FBDEV_EMULATION
        struct tegra_drm *tegra = drm->dev_private;
 
        tegra->fbdev = tegra_fbdev_create(drm);
@@ -383,7 +383,7 @@ int tegra_drm_fb_prepare(struct drm_device *drm)
 
 void tegra_drm_fb_free(struct drm_device *drm)
 {
-#ifdef CONFIG_DRM_TEGRA_FBDEV
+#ifdef CONFIG_DRM_FBDEV_EMULATION
        struct tegra_drm *tegra = drm->dev_private;
 
        tegra_fbdev_free(tegra->fbdev);
@@ -392,7 +392,7 @@ void tegra_drm_fb_free(struct drm_device *drm)
 
 int tegra_drm_fb_init(struct drm_device *drm)
 {
-#ifdef CONFIG_DRM_TEGRA_FBDEV
+#ifdef CONFIG_DRM_FBDEV_EMULATION
        struct tegra_drm *tegra = drm->dev_private;
        int err;
 
@@ -407,7 +407,7 @@ int tegra_drm_fb_init(struct drm_device *drm)
 
 void tegra_drm_fb_exit(struct drm_device *drm)
 {
-#ifdef CONFIG_DRM_TEGRA_FBDEV
+#ifdef CONFIG_DRM_FBDEV_EMULATION
        struct tegra_drm *tegra = drm->dev_private;
 
        tegra_fbdev_exit(tegra->fbdev);
index bb9d0de..1252108 100644 (file)
 # define DP_EDP_14                         0x03
 
 #define DP_EDP_GENERAL_CAP_1               0x701
+# define DP_EDP_TCON_BACKLIGHT_ADJUSTMENT_CAP          (1 << 0)
+# define DP_EDP_BACKLIGHT_PIN_ENABLE_CAP               (1 << 1)
+# define DP_EDP_BACKLIGHT_AUX_ENABLE_CAP               (1 << 2)
+# define DP_EDP_PANEL_SELF_TEST_PIN_ENABLE_CAP         (1 << 3)
+# define DP_EDP_PANEL_SELF_TEST_AUX_ENABLE_CAP         (1 << 4)
+# define DP_EDP_FRC_ENABLE_CAP                         (1 << 5)
+# define DP_EDP_COLOR_ENGINE_CAP                       (1 << 6)
+# define DP_EDP_SET_POWER_CAP                          (1 << 7)
 
 #define DP_EDP_BACKLIGHT_ADJUSTMENT_CAP     0x702
+# define DP_EDP_BACKLIGHT_BRIGHTNESS_PWM_PIN_CAP       (1 << 0)
+# define DP_EDP_BACKLIGHT_BRIGHTNESS_AUX_SET_CAP       (1 << 1)
+# define DP_EDP_BACKLIGHT_BRIGHTNESS_BYTE_COUNT                (1 << 2)
+# define DP_EDP_BACKLIGHT_AUX_PWM_PRODUCT_CAP          (1 << 3)
+# define DP_EDP_BACKLIGHT_FREQ_PWM_PIN_PASSTHRU_CAP    (1 << 4)
+# define DP_EDP_BACKLIGHT_FREQ_AUX_SET_CAP             (1 << 5)
+# define DP_EDP_DYNAMIC_BACKLIGHT_CAP                  (1 << 6)
+# define DP_EDP_VBLANK_BACKLIGHT_UPDATE_CAP            (1 << 7)
 
 #define DP_EDP_GENERAL_CAP_2               0x703
+# define DP_EDP_OVERDRIVE_ENGINE_ENABLED               (1 << 0)
 
 #define DP_EDP_GENERAL_CAP_3               0x704    /* eDP 1.4 */
+# define DP_EDP_X_REGION_CAP_MASK                      (0xf << 0)
+# define DP_EDP_X_REGION_CAP_SHIFT                     0
+# define DP_EDP_Y_REGION_CAP_MASK                      (0xf << 4)
+# define DP_EDP_Y_REGION_CAP_SHIFT                     4
 
 #define DP_EDP_DISPLAY_CONTROL_REGISTER     0x720
+# define DP_EDP_BACKLIGHT_ENABLE                       (1 << 0)
+# define DP_EDP_BLACK_VIDEO_ENABLE                     (1 << 1)
+# define DP_EDP_FRC_ENABLE                             (1 << 2)
+# define DP_EDP_COLOR_ENGINE_ENABLE                    (1 << 3)
+# define DP_EDP_VBLANK_BACKLIGHT_UPDATE_ENABLE         (1 << 7)
 
 #define DP_EDP_BACKLIGHT_MODE_SET_REGISTER  0x721
+# define DP_EDP_BACKLIGHT_CONTROL_MODE_MASK            (3 << 0)
+# define DP_EDP_BACKLIGHT_CONTROL_MODE_PWM             (0 << 0)
+# define DP_EDP_BACKLIGHT_CONTROL_MODE_PRESET          (1 << 0)
+# define DP_EDP_BACKLIGHT_CONTROL_MODE_DPCD            (2 << 0)
+# define DP_EDP_BACKLIGHT_CONTROL_MODE_PRODUCT         (3 << 0)
+# define DP_EDP_BACKLIGHT_FREQ_PWM_PIN_PASSTHRU_ENABLE (1 << 2)
+# define DP_EDP_BACKLIGHT_FREQ_AUX_SET_ENABLE          (1 << 3)
+# define DP_EDP_DYNAMIC_BACKLIGHT_ENABLE               (1 << 4)
+# define DP_EDP_REGIONAL_BACKLIGHT_ENABLE              (1 << 5)
+# define DP_EDP_UPDATE_REGION_BRIGHTNESS               (1 << 6) /* eDP 1.4 */
 
 #define DP_EDP_BACKLIGHT_BRIGHTNESS_MSB     0x722
 #define DP_EDP_BACKLIGHT_BRIGHTNESS_LSB     0x723
index 15e7f00..0b3e11a 100644 (file)
  */
 
 /**
- * This structure defines the drm_mm memory object, which will be used by the
- * DRM for its buffer objects.
+ * struct drm_gem_object - GEM buffer object
+ *
+ * This structure defines the generic parts for GEM buffer objects, which are
+ * mostly around handling mmap and userspace handles.
+ *
+ * Buffer objects are often abbreviated to BO.
  */
 struct drm_gem_object {
-       /** Reference count of this object */
+       /**
+        * @refcount:
+        *
+        * Reference count of this object
+        *
+        * Please use drm_gem_object_reference() to acquire and
+        * drm_gem_object_unreference() or drm_gem_object_unreference_unlocked()
+        * to release a reference to a GEM buffer object.
+        */
        struct kref refcount;
 
        /**
-        * handle_count - gem file_priv handle count of this object
+        * @handle_count:
+        *
+        * This is the GEM file_priv handle count of this object.
         *
         * Each handle also holds a reference. Note that when the handle_count
         * drops to 0 any global names (e.g. the id in the flink namespace) will
         * be cleared.
         *
         * Protected by dev->object_name_lock.
-        * */
+        */
        unsigned handle_count;
 
-       /** Related drm device */
+       /**
+        * @dev: DRM dev this object belongs to.
+        */
        struct drm_device *dev;
 
-       /** File representing the shmem storage */
+       /**
+        * @filp:
+        *
+        * SHMEM file node used as backing storage for swappable buffer objects.
+        * GEM also supports driver private objects with driver-specific backing
+        * storage (contiguous CMA memory, special reserved blocks). In this
+        * case @filp is NULL.
+        */
        struct file *filp;
 
-       /* Mapping info for this object */
+       /**
+        * @vma_node:
+        *
+        * Mapping info for this object to support mmap. Drivers are supposed to
+        * allocate the mmap offset using drm_gem_create_mmap_offset(). The
+        * offset itself can be retrieved using drm_vma_node_offset_addr().
+        *
+        * Memory mapping itself is handled by drm_gem_mmap(), which also checks
+        * that userspace is allowed to access the object.
+        */
        struct drm_vma_offset_node vma_node;
 
        /**
+        * @size:
+        *
         * Size of the object, in bytes.  Immutable over the object's
         * lifetime.
         */
        size_t size;
 
        /**
+        * @name:
+        *
         * Global name for this object, starts at 1. 0 means unnamed.
-        * Access is covered by the object_name_lock in the related drm_device
+        * Access is covered by dev->object_name_lock. This is used by the GEM_FLINK
+        * and GEM_OPEN ioctls.
         */
        int name;
 
        /**
-        * Memory domains. These monitor which caches contain read/write data
+        * @read_domains:
+        *
+        * Read memory domains. These monitor which caches contain read/write data
         * related to the object. When transitioning from one set of domains
         * to another, the driver is called to ensure that caches are suitably
-        * flushed and invalidated
+        * flushed and invalidated.
         */
        uint32_t read_domains;
+
+       /**
+        * @write_domain: Corresponding unique write memory domain.
+        */
        uint32_t write_domain;
 
        /**
+        * @pending_read_domains:
+        *
         * While validating an exec operation, the
         * new read/write domain values are computed here.
         * They will be transferred to the above values
         * at the point that any cache flushing occurs
         */
        uint32_t pending_read_domains;
+
+       /**
+        * @pending_write_domain: Write domain similar to @pending_read_domains.
+        */
        uint32_t pending_write_domain;
 
        /**
-        * dma_buf - dma buf associated with this GEM object
+        * @dma_buf:
+        *
+        * dma-buf associated with this GEM object.
         *
         * Pointer to the dma-buf associated with this gem object (either
         * through importing or exporting). We break the resulting reference
         * loop when the last gem handle for this object is released.
         *
-        * Protected by obj->object_name_lock
+        * Protected by obj->object_name_lock.
         */
        struct dma_buf *dma_buf;
 
        /**
-        * import_attach - dma buf attachment backing this object
+        * @import_attach:
+        *
+        * dma-buf attachment backing this object.
         *
         * Any foreign dma_buf imported as a gem object has this set to the
         * attachment point for the device. This is invariant over the lifetime
@@ -133,12 +186,30 @@ int drm_gem_mmap_obj(struct drm_gem_object *obj, unsigned long obj_size,
                     struct vm_area_struct *vma);
 int drm_gem_mmap(struct file *filp, struct vm_area_struct *vma);
 
+/**
+ * drm_gem_object_reference - acquire a GEM BO reference
+ * @obj: GEM buffer object
+ *
+ * This acquires additional reference to @obj. It is illegal to call this
+ * without already holding a reference. No locks required.
+ */
 static inline void
 drm_gem_object_reference(struct drm_gem_object *obj)
 {
        kref_get(&obj->refcount);
 }
 
+/**
+ * drm_gem_object_unreference - release a GEM BO reference
+ * @obj: GEM buffer object
+ *
+ * This releases a reference to @obj. Callers must hold the dev->struct_mutex
+ * lock when calling this function, even when the driver doesn't use
+ * dev->struct_mutex for anything.
+ *
+ * For drivers not encumbered with legacy locking use
+ * drm_gem_object_unreference_unlocked() instead.
+ */
 static inline void
 drm_gem_object_unreference(struct drm_gem_object *obj)
 {
@@ -149,6 +220,13 @@ drm_gem_object_unreference(struct drm_gem_object *obj)
        }
 }
 
+/**
+ * drm_gem_object_unreference_unlocked - release a GEM BO reference
+ * @obj: GEM buffer object
+ *
+ * This releases a reference to @obj. Callers must not hold the
+ * dev->struct_mutex lock when calling this function.
+ */
 static inline void
 drm_gem_object_unreference_unlocked(struct drm_gem_object *obj)
 {