drm: Update GEM refcounting docs

          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

          abstracted from the client in libdrm.

        </para>

      </sect3>

      <sect3>

    </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>

 */

/**

 * 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

		     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)

{

	}

}

/**

 * 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)

{