diff mbox

[6/6] drm: Update TTM initialization documentation

Message ID 20161228143216.26821-7-krisman@collabora.co.uk (mailing list archive)
State New, archived
Headers show

Commit Message

Gabriel Krisman Bertazi Dec. 28, 2016, 2:32 p.m. UTC
ttm_global_reference was renamed to drm_global_reference.  This updates
the documentation to reflect that.  While we are there, document the
drm_global_reference API and update the initialization interface
documentation.

Signed-off-by: Gabriel Krisman Bertazi <krisman@collabora.co.uk>
---
 Documentation/gpu/drm-mm.rst | 30 +++++++++++++++++-------------
 drivers/gpu/drm/drm_global.c | 23 +++++++++++++++++++++++
 2 files changed, 40 insertions(+), 13 deletions(-)

Comments

Daniel Vetter Dec. 30, 2016, 11:49 a.m. UTC | #1
On Wed, Dec 28, 2016 at 12:32:16PM -0200, Gabriel Krisman Bertazi wrote:
> ttm_global_reference was renamed to drm_global_reference.  This updates
> the documentation to reflect that.  While we are there, document the
> drm_global_reference API and update the initialization interface
> documentation.
> 
> Signed-off-by: Gabriel Krisman Bertazi <krisman@collabora.co.uk>

Also merged patches 3,5&6.

Thanks, Daniel

> ---
>  Documentation/gpu/drm-mm.rst | 30 +++++++++++++++++-------------
>  drivers/gpu/drm/drm_global.c | 23 +++++++++++++++++++++++
>  2 files changed, 40 insertions(+), 13 deletions(-)
> 
> diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst
> index cb5daffcd6be..3686ed148003 100644
> --- a/Documentation/gpu/drm-mm.rst
> +++ b/Documentation/gpu/drm-mm.rst
> @@ -33,26 +33,24 @@ TTM design background and information belongs here.
>  TTM initialization
>  ------------------
>  
> -    **Warning**
> +Drivers wishing to support TTM must pass a filled :c:type:`ttm_bo_driver
> +<ttm_bo_driver>` structure to ttm_bo_device_init, together with an
> +initialized global reference to the memory manager.  The ttm_bo_driver
> +structure contains several fields with function pointers for
> +initializing the TTM, allocating and freeing memory, waiting for command
> +completion and fence synchronization, and memory migration.
>  
> -    This section is outdated.
> -
> -Drivers wishing to support TTM must fill out a drm_bo_driver
> -structure. The structure contains several fields with function pointers
> -for initializing the TTM, allocating and freeing memory, waiting for
> -command completion and fence synchronization, and memory migration. See
> -the radeon_ttm.c file for an example of usage.
> -
> -The ttm_global_reference structure is made up of several fields:
> +The :c:type:`struct drm_global_reference <drm_global_reference>` is made
> +up of several fields:
>  
>  .. code-block:: c
>  
> -              struct ttm_global_reference {
> +              struct drm_global_reference {
>                        enum ttm_global_types global_type;
>                        size_t size;
>                        void *object;
> -                      int (*init) (struct ttm_global_reference *);
> -                      void (*release) (struct ttm_global_reference *);
> +                      int (*init) (struct drm_global_reference *);
> +                      void (*release) (struct drm_global_reference *);
>                };
>  
>  
> @@ -76,6 +74,12 @@ ttm_bo_global_release(), respectively. Also, like the previous
>  object, ttm_global_item_ref() is used to create an initial reference
>  count for the TTM, which will call your initialization function.
>  
> +See the radeon_ttm.c file for an example of usage.
> +
> +.. kernel-doc:: drivers/gpu/drm/drm_global.c
> +   :export:
> +
> +
>  The Graphics Execution Manager (GEM)
>  ====================================
>  
> diff --git a/drivers/gpu/drm/drm_global.c b/drivers/gpu/drm/drm_global.c
> index b404287abb97..b2dc21e33ae0 100644
> --- a/drivers/gpu/drm/drm_global.c
> +++ b/drivers/gpu/drm/drm_global.c
> @@ -63,6 +63,18 @@ void drm_global_release(void)
>  	}
>  }
>  
> +/**
> + * drm_global_item_ref - Initialize and acquire reference to memory
> + * object
> + * @ref: Object for initialization
> + *
> + * This initializes a memory object, allocating memory and calling the
> + * .init() hook. Further calls will increase the reference count for
> + * that item.
> + *
> + * Returns:
> + * Zero on success, non-zero otherwise.
> + */
>  int drm_global_item_ref(struct drm_global_reference *ref)
>  {
>  	int ret = 0;
> @@ -97,6 +109,17 @@ int drm_global_item_ref(struct drm_global_reference *ref)
>  }
>  EXPORT_SYMBOL(drm_global_item_ref);
>  
> +/**
> + * drm_global_item_unref - Drop reference to memory
> + * object
> + * @ref: Object being removed
> + *
> + * Drop a reference to the memory object and eventually call the
> + * release() hook.  The allocated object should be dropped in the
> + * release() hook or before calling this function
> + *
> + */
> +
>  void drm_global_item_unref(struct drm_global_reference *ref)
>  {
>  	struct drm_global_item *item = &glob[ref->global_type];
> -- 
> 2.11.0
> 
> _______________________________________________
> dri-devel mailing list
> dri-devel@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/dri-devel
Daniel Vetter Dec. 30, 2016, 11:53 a.m. UTC | #2
On Wed, Dec 28, 2016 at 12:32:16PM -0200, Gabriel Krisman Bertazi wrote:
> ttm_global_reference was renamed to drm_global_reference.  This updates
> the documentation to reflect that.  While we are there, document the
> drm_global_reference API and update the initialization interface
> documentation.
> 
> Signed-off-by: Gabriel Krisman Bertazi <krisman@collabora.co.uk>
> ---
>  Documentation/gpu/drm-mm.rst | 30 +++++++++++++++++-------------
>  drivers/gpu/drm/drm_global.c | 23 +++++++++++++++++++++++
>  2 files changed, 40 insertions(+), 13 deletions(-)
> 
> diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst
> index cb5daffcd6be..3686ed148003 100644
> --- a/Documentation/gpu/drm-mm.rst
> +++ b/Documentation/gpu/drm-mm.rst
> @@ -33,26 +33,24 @@ TTM design background and information belongs here.
>  TTM initialization
>  ------------------
>  
> -    **Warning**
> +Drivers wishing to support TTM must pass a filled :c:type:`ttm_bo_driver
> +<ttm_bo_driver>` structure to ttm_bo_device_init, together with an
> +initialized global reference to the memory manager.  The ttm_bo_driver
> +structure contains several fields with function pointers for
> +initializing the TTM, allocating and freeing memory, waiting for command
> +completion and fence synchronization, and memory migration.
>  
> -    This section is outdated.

Forgot to mention: I kept this warning, since TTM docs are still massively
inadequate.
-Daniel

> -
> -Drivers wishing to support TTM must fill out a drm_bo_driver
> -structure. The structure contains several fields with function pointers
> -for initializing the TTM, allocating and freeing memory, waiting for
> -command completion and fence synchronization, and memory migration. See
> -the radeon_ttm.c file for an example of usage.
> -
> -The ttm_global_reference structure is made up of several fields:
> +The :c:type:`struct drm_global_reference <drm_global_reference>` is made
> +up of several fields:
>  
>  .. code-block:: c
>  
> -              struct ttm_global_reference {
> +              struct drm_global_reference {
>                        enum ttm_global_types global_type;
>                        size_t size;
>                        void *object;
> -                      int (*init) (struct ttm_global_reference *);
> -                      void (*release) (struct ttm_global_reference *);
> +                      int (*init) (struct drm_global_reference *);
> +                      void (*release) (struct drm_global_reference *);
>                };
>  
>  
> @@ -76,6 +74,12 @@ ttm_bo_global_release(), respectively. Also, like the previous
>  object, ttm_global_item_ref() is used to create an initial reference
>  count for the TTM, which will call your initialization function.
>  
> +See the radeon_ttm.c file for an example of usage.
> +
> +.. kernel-doc:: drivers/gpu/drm/drm_global.c
> +   :export:
> +
> +
>  The Graphics Execution Manager (GEM)
>  ====================================
>  
> diff --git a/drivers/gpu/drm/drm_global.c b/drivers/gpu/drm/drm_global.c
> index b404287abb97..b2dc21e33ae0 100644
> --- a/drivers/gpu/drm/drm_global.c
> +++ b/drivers/gpu/drm/drm_global.c
> @@ -63,6 +63,18 @@ void drm_global_release(void)
>  	}
>  }
>  
> +/**
> + * drm_global_item_ref - Initialize and acquire reference to memory
> + * object
> + * @ref: Object for initialization
> + *
> + * This initializes a memory object, allocating memory and calling the
> + * .init() hook. Further calls will increase the reference count for
> + * that item.
> + *
> + * Returns:
> + * Zero on success, non-zero otherwise.
> + */
>  int drm_global_item_ref(struct drm_global_reference *ref)
>  {
>  	int ret = 0;
> @@ -97,6 +109,17 @@ int drm_global_item_ref(struct drm_global_reference *ref)
>  }
>  EXPORT_SYMBOL(drm_global_item_ref);
>  
> +/**
> + * drm_global_item_unref - Drop reference to memory
> + * object
> + * @ref: Object being removed
> + *
> + * Drop a reference to the memory object and eventually call the
> + * release() hook.  The allocated object should be dropped in the
> + * release() hook or before calling this function
> + *
> + */
> +
>  void drm_global_item_unref(struct drm_global_reference *ref)
>  {
>  	struct drm_global_item *item = &glob[ref->global_type];
> -- 
> 2.11.0
> 
> _______________________________________________
> dri-devel mailing list
> dri-devel@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/dri-devel
diff mbox

Patch

diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst
index cb5daffcd6be..3686ed148003 100644
--- a/Documentation/gpu/drm-mm.rst
+++ b/Documentation/gpu/drm-mm.rst
@@ -33,26 +33,24 @@  TTM design background and information belongs here.
 TTM initialization
 ------------------
 
-    **Warning**
+Drivers wishing to support TTM must pass a filled :c:type:`ttm_bo_driver
+<ttm_bo_driver>` structure to ttm_bo_device_init, together with an
+initialized global reference to the memory manager.  The ttm_bo_driver
+structure contains several fields with function pointers for
+initializing the TTM, allocating and freeing memory, waiting for command
+completion and fence synchronization, and memory migration.
 
-    This section is outdated.
-
-Drivers wishing to support TTM must fill out a drm_bo_driver
-structure. The structure contains several fields with function pointers
-for initializing the TTM, allocating and freeing memory, waiting for
-command completion and fence synchronization, and memory migration. See
-the radeon_ttm.c file for an example of usage.
-
-The ttm_global_reference structure is made up of several fields:
+The :c:type:`struct drm_global_reference <drm_global_reference>` is made
+up of several fields:
 
 .. code-block:: c
 
-              struct ttm_global_reference {
+              struct drm_global_reference {
                       enum ttm_global_types global_type;
                       size_t size;
                       void *object;
-                      int (*init) (struct ttm_global_reference *);
-                      void (*release) (struct ttm_global_reference *);
+                      int (*init) (struct drm_global_reference *);
+                      void (*release) (struct drm_global_reference *);
               };
 
 
@@ -76,6 +74,12 @@  ttm_bo_global_release(), respectively. Also, like the previous
 object, ttm_global_item_ref() is used to create an initial reference
 count for the TTM, which will call your initialization function.
 
+See the radeon_ttm.c file for an example of usage.
+
+.. kernel-doc:: drivers/gpu/drm/drm_global.c
+   :export:
+
+
 The Graphics Execution Manager (GEM)
 ====================================
 
diff --git a/drivers/gpu/drm/drm_global.c b/drivers/gpu/drm/drm_global.c
index b404287abb97..b2dc21e33ae0 100644
--- a/drivers/gpu/drm/drm_global.c
+++ b/drivers/gpu/drm/drm_global.c
@@ -63,6 +63,18 @@  void drm_global_release(void)
 	}
 }
 
+/**
+ * drm_global_item_ref - Initialize and acquire reference to memory
+ * object
+ * @ref: Object for initialization
+ *
+ * This initializes a memory object, allocating memory and calling the
+ * .init() hook. Further calls will increase the reference count for
+ * that item.
+ *
+ * Returns:
+ * Zero on success, non-zero otherwise.
+ */
 int drm_global_item_ref(struct drm_global_reference *ref)
 {
 	int ret = 0;
@@ -97,6 +109,17 @@  int drm_global_item_ref(struct drm_global_reference *ref)
 }
 EXPORT_SYMBOL(drm_global_item_ref);
 
+/**
+ * drm_global_item_unref - Drop reference to memory
+ * object
+ * @ref: Object being removed
+ *
+ * Drop a reference to the memory object and eventually call the
+ * release() hook.  The allocated object should be dropped in the
+ * release() hook or before calling this function
+ *
+ */
+
 void drm_global_item_unref(struct drm_global_reference *ref)
 {
 	struct drm_global_item *item = &glob[ref->global_type];