kernel / kernel-source

Clone
Source Code
GIT

Files

  1.   a07f7ac44cacae01a70ddaee4b6440c9e8a59054
  2.   patches.suse
  3.   7661-drm-amdgpu-fix-ups-for-amdgpu_object-c-documentation
Blob Blame History Raw 
From: =?UTF-8?q?Michel=20D=C3=A4nzer?= <michel.daenzer@amd.com>
Date: Fri, 1 Jun 2018 12:29:45 +0200
Subject: drm/amdgpu: Fix-ups for amdgpu_object.c documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Git-commit: 2472e11b85f08e56519b988c4b76c610c818b1b0
Patch-mainline: v4.19-rc1
References: FATE#326289 FATE#326079 FATE#326049 FATE#322398 FATE#326166

* Fix format of return value descriptions
* Document all parameters of amdgpu_bo_free_kernel
* Document amdgpu_bo_get_preferred_pin_domain

Reviewed-by: Alex Deucher <alexander.deucher@amd.com>
Signed-off-by: Michel Dänzer <michel.daenzer@amd.com>
Signed-off-by: Alex Deucher <alexander.deucher@amd.com>
Acked-by: Petr Tesarik <ptesarik@suse.com>
---
 drivers/gpu/drm/amd/amdgpu/amdgpu_object.c |   78 ++++++++++++++++++++---------
 1 file changed, 55 insertions(+), 23 deletions(-)

--- a/drivers/gpu/drm/amd/amdgpu/amdgpu_object.c
+++ b/drivers/gpu/drm/amd/amdgpu/amdgpu_object.c
@@ -93,7 +93,8 @@ static void amdgpu_ttm_bo_destroy(struct
  * Uses destroy function associated with the object to determine if this is
  * an &amdgpu_bo.
  *
- * Returns true if the object belongs to &amdgpu_bo, false if not.
+ * Returns:
+ * true if the object belongs to &amdgpu_bo, false if not.
  */
 bool amdgpu_ttm_bo_is_amdgpu_bo(struct ttm_buffer_object *bo)
 {
@@ -214,7 +215,8 @@ void amdgpu_ttm_placement_from_domain(st
  *
  * Note: For bo_ptr new BO is only created if bo_ptr points to NULL.
  *
- * Returns 0 on success, negative error code otherwise.
+ * Returns:
+ * 0 on success, negative error code otherwise.
  */
 int amdgpu_bo_create_reserved(struct amdgpu_device *adev,
 			      unsigned long size, int align,
@@ -291,7 +293,8 @@ error_free:
  *
  * Note: For bo_ptr new BO is only created if bo_ptr points to NULL.
  *
- * Returns 0 on success, negative error code otherwise.
+ * Returns:
+ * 0 on success, negative error code otherwise.
  */
 int amdgpu_bo_create_kernel(struct amdgpu_device *adev,
 			    unsigned long size, int align,
@@ -315,6 +318,8 @@ int amdgpu_bo_create_kernel(struct amdgp
  * amdgpu_bo_free_kernel - free BO for kernel use
  *
  * @bo: amdgpu BO to free
+ * @gpu_addr: pointer to where the BO's GPU memory space address was stored
+ * @cpu_addr: pointer to where the BO's CPU memory space address was stored
  *
  * unmaps and unpin a BO for kernel internal use.
  */
@@ -539,7 +544,8 @@ static int amdgpu_bo_create_shadow(struc
  * Shadow object is used to backup the original buffer object, and is always
  * in GTT.
  *
- * Returns 0 for success or a negative error code on failure.
+ * Returns:
+ * 0 for success or a negative error code on failure.
  */
 int amdgpu_bo_create(struct amdgpu_device *adev,
 		     struct amdgpu_bo_param *bp,
@@ -582,7 +588,8 @@ int amdgpu_bo_create(struct amdgpu_devic
  * Copies an &amdgpu_bo buffer object to its shadow object.
  * Not used for now.
  *
- * Returns 0 for success or a negative error code on failure.
+ * Returns:
+ * 0 for success or a negative error code on failure.
  */
 int amdgpu_bo_backup_to_shadow(struct amdgpu_device *adev,
 			       struct amdgpu_ring *ring,
@@ -625,7 +632,8 @@ err:
  * This is used for validating shadow bos.  It calls ttm_bo_validate() to
  * make sure the buffer is resident where it needs to be.
  *
- * Returns 0 for success or a negative error code on failure.
+ * Returns:
+ * 0 for success or a negative error code on failure.
  */
 int amdgpu_bo_validate(struct amdgpu_bo *bo)
 {
@@ -662,7 +670,8 @@ retry:
  * This is used for recovering a buffer from its shadow in case of a gpu
  * reset where vram context may be lost.
  *
- * Returns 0 for success or a negative error code on failure.
+ * Returns:
+ * 0 for success or a negative error code on failure.
  */
 int amdgpu_bo_restore_from_shadow(struct amdgpu_device *adev,
 				  struct amdgpu_ring *ring,
@@ -704,7 +713,8 @@ err:
  * Calls ttm_bo_kmap() to set up the kernel virtual mapping; calls
  * amdgpu_bo_kptr() to get the kernel virtual address.
  *
- * Returns 0 for success or a negative error code on failure.
+ * Returns:
+ * 0 for success or a negative error code on failure.
  */
 int amdgpu_bo_kmap(struct amdgpu_bo *bo, void **ptr)
 {
@@ -742,7 +752,8 @@ int amdgpu_bo_kmap(struct amdgpu_bo *bo,
  *
  * Calls ttm_kmap_obj_virtual() to get the kernel virtual address
  *
- * Returns the virtual address of a buffer object area.
+ * Returns:
+ * the virtual address of a buffer object area.
  */
 void *amdgpu_bo_kptr(struct amdgpu_bo *bo)
 {
@@ -769,7 +780,8 @@ void amdgpu_bo_kunmap(struct amdgpu_bo *
  *
  * References the contained &ttm_buffer_object.
  *
- * Returns a refcounted pointer to the &amdgpu_bo buffer object.
+ * Returns:
+ * a refcounted pointer to the &amdgpu_bo buffer object.
  */
 struct amdgpu_bo *amdgpu_bo_ref(struct amdgpu_bo *bo)
 {
@@ -819,7 +831,8 @@ void amdgpu_bo_unref(struct amdgpu_bo **
  * where to pin a buffer if there are specific restrictions on where a buffer
  * must be located.
  *
- * Returns 0 for success or a negative error code on failure.
+ * Returns:
+ * 0 for success or a negative error code on failure.
  */
 int amdgpu_bo_pin_restricted(struct amdgpu_bo *bo, u32 domain,
 			     u64 min_offset, u64 max_offset,
@@ -924,7 +937,8 @@ error:
  * Provides a simpler API for buffers that do not have any strict restrictions
  * on where a buffer must be located.
  *
- * Returns 0 for success or a negative error code on failure.
+ * Returns:
+ * 0 for success or a negative error code on failure.
  */
 int amdgpu_bo_pin(struct amdgpu_bo *bo, u32 domain, u64 *gpu_addr)
 {
@@ -938,7 +952,8 @@ int amdgpu_bo_pin(struct amdgpu_bo *bo,
  * Decreases the pin_count, and clears the flags if pin_count reaches 0.
  * Changes placement and pin size accordingly.
  *
- * Returns 0 for success or a negative error code on failure.
+ * Returns:
+ * 0 for success or a negative error code on failure.
  */
 int amdgpu_bo_unpin(struct amdgpu_bo *bo)
 {
@@ -979,7 +994,8 @@ int amdgpu_bo_unpin(struct amdgpu_bo *bo
  * Evicts all VRAM buffers on the lru list of the memory type.
  * Mainly used for evicting vram at suspend time.
  *
- * Returns 0 for success or a negative error code on failure.
+ * Returns:
+ * 0 for success or a negative error code on failure.
  */
 int amdgpu_bo_evict_vram(struct amdgpu_device *adev)
 {
@@ -1009,7 +1025,8 @@ static const char *amdgpu_vram_names[] =
  *
  * Calls amdgpu_ttm_init() to initialize amdgpu memory manager.
  *
- * Returns 0 for success or a negative error code on failure.
+ * Returns:
+ * 0 for success or a negative error code on failure.
  */
 int amdgpu_bo_init(struct amdgpu_device *adev)
 {
@@ -1035,7 +1052,8 @@ int amdgpu_bo_init(struct amdgpu_device
  * Calls amdgpu_ttm_late_init() to free resources used earlier during
  * initialization.
  *
- * Returns 0 for success or a negative error code on failure.
+ * Returns:
+ * 0 for success or a negative error code on failure.
  */
 int amdgpu_bo_late_init(struct amdgpu_device *adev)
 {
@@ -1064,7 +1082,8 @@ void amdgpu_bo_fini(struct amdgpu_device
  *
  * Calls ttm_fbdev_mmap() to mmap fbdev memory if it is backed by a bo.
  *
- * Returns 0 for success or a negative error code on failure.
+ * Returns:
+ * 0 for success or a negative error code on failure.
  */
 int amdgpu_bo_fbdev_mmap(struct amdgpu_bo *bo,
 			     struct vm_area_struct *vma)
@@ -1080,7 +1099,8 @@ int amdgpu_bo_fbdev_mmap(struct amdgpu_b
  * Sets buffer object's tiling flags with the new one. Used by GEM ioctl or
  * kernel driver to set the tiling flags on a buffer.
  *
- * Returns 0 for success or a negative error code on failure.
+ * Returns:
+ * 0 for success or a negative error code on failure.
  */
 int amdgpu_bo_set_tiling_flags(struct amdgpu_bo *bo, u64 tiling_flags)
 {
@@ -1120,7 +1140,8 @@ void amdgpu_bo_get_tiling_flags(struct a
  * Sets buffer object's metadata, its size and flags.
  * Used via GEM ioctl.
  *
- * Returns 0 for success or a negative error code on failure.
+ * Returns:
+ * 0 for success or a negative error code on failure.
  */
 int amdgpu_bo_set_metadata (struct amdgpu_bo *bo, void *metadata,
 			    uint32_t metadata_size, uint64_t flags)
@@ -1163,7 +1184,8 @@ int amdgpu_bo_set_metadata (struct amdgp
  * less than metadata_size.
  * Used via GEM ioctl.
  *
- * Returns 0 for success or a negative error code on failure.
+ * Returns:
+ * 0 for success or a negative error code on failure.
  */
 int amdgpu_bo_get_metadata(struct amdgpu_bo *bo, void *buffer,
 			   size_t buffer_size, uint32_t *metadata_size,
@@ -1234,7 +1256,8 @@ void amdgpu_bo_move_notify(struct ttm_bu
  * also performs bookkeeping.
  * TTM driver callback for dealing with vm faults.
  *
- * Returns 0 for success or a negative error code on failure.
+ * Returns:
+ * 0 for success or a negative error code on failure.
  */
 int amdgpu_bo_fault_reserve_notify(struct ttm_buffer_object *bo)
 {
@@ -1309,10 +1332,11 @@ void amdgpu_bo_fence(struct amdgpu_bo *b
  * amdgpu_bo_gpu_offset - return GPU offset of bo
  * @bo:	amdgpu object for which we query the offset
  *
- * Returns current GPU offset of the object.
- *
  * Note: object should either be pinned or reserved when calling this
  * function, it might be useful to add check for this for debugging.
+ *
+ * Returns:
+ * current GPU offset of the object.
  */
 u64 amdgpu_bo_gpu_offset(struct amdgpu_bo *bo)
 {
@@ -1328,6 +1352,14 @@ u64 amdgpu_bo_gpu_offset(struct amdgpu_b
 	return bo->tbo.offset;
 }
 
+/**
+ * amdgpu_bo_get_preferred_pin_domain - get preferred domain for scanout
+ * @adev: amdgpu device object
+ * @domain: allowed :ref:`memory domains <amdgpu_memory_domains>`
+ *
+ * Returns:
+ * Which of the allowed domains is preferred for pinning the BO for scanout.
+ */
 uint32_t amdgpu_bo_get_preferred_pin_domain(struct amdgpu_device *adev,
 					    uint32_t domain)
 {
Powered by Pagure 5.13.3
Documentation • About this Instance • SSH Hostkey/Fingerprint
© Red Hat, Inc. and others.