From 2472e11b85f08e56519b988c4b76c610c818b1b0 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Michel=20D=C3=A4nzer?= Date: Fri, 1 Jun 2018 12:29:45 +0200 Subject: [PATCH] drm/amdgpu: Fix-ups for amdgpu_object.c documentation MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit * 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 Signed-off-by: Michel Dänzer Signed-off-by: Alex Deucher --- drivers/gpu/drm/amd/amdgpu/amdgpu_object.c | 78 +++++++++++++++++++++--------- 1 file changed, 55 insertions(+), 23 deletions(-) diff --git a/drivers/gpu/drm/amd/amdgpu/amdgpu_object.c b/drivers/gpu/drm/amd/amdgpu/amdgpu_object.c index 78d75ae5932f..987a9fa33d35 100644 --- 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 ttm_buffer_object *tbo) * 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(struct amdgpu_bo *abo, u32 domain) * * 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 amdgpu_device *adev, * 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(struct amdgpu_device *adev, * 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_device *adev, * 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, void **ptr) * * 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 *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 **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, @@ -925,7 +938,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) { @@ -939,7 +953,8 @@ int amdgpu_bo_pin(struct amdgpu_bo *bo, u32 domain, u64 *gpu_addr) * 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) { @@ -983,7 +998,8 @@ error: * 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) { @@ -1013,7 +1029,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) { @@ -1039,7 +1056,8 @@ int amdgpu_bo_init(struct amdgpu_device *adev) * 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) { @@ -1068,7 +1086,8 @@ void amdgpu_bo_fini(struct amdgpu_device *adev) * * 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) @@ -1084,7 +1103,8 @@ int amdgpu_bo_fbdev_mmap(struct amdgpu_bo *bo, * 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) { @@ -1124,7 +1144,8 @@ void amdgpu_bo_get_tiling_flags(struct amdgpu_bo *bo, u64 *tiling_flags) * 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) @@ -1167,7 +1188,8 @@ int amdgpu_bo_set_metadata (struct amdgpu_bo *bo, void *metadata, * 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, @@ -1238,7 +1260,8 @@ void amdgpu_bo_move_notify(struct ttm_buffer_object *bo, * 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) { @@ -1313,10 +1336,11 @@ void amdgpu_bo_fence(struct amdgpu_bo *bo, struct dma_fence *fence, * 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) { @@ -1332,6 +1356,14 @@ u64 amdgpu_bo_gpu_offset(struct amdgpu_bo *bo) return bo->tbo.offset; } +/** + * amdgpu_bo_get_preferred_pin_domain - get preferred domain for scanout + * @adev: amdgpu device object + * @domain: allowed :ref:`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) { -- 2.11.0