[PATCH 1/1] drm/amdgpu: add kernel doc for amdgpu_object.c
Samuel Li
samuel.li at amd.com
Fri May 18 20:35:12 UTC 2018
On 2018-05-18 02:54 PM, Alex Deucher wrote:
> On Thu, May 17, 2018 at 6:20 PM, Samuel Li <Samuel.Li at amd.com> wrote:
>> Signed-off-by: Samuel Li <Samuel.Li at amd.com>
>
> Please also add a separate DOC section at the top of this file giving
> a brief overview of how amdgpu bo API works. E.g., how you would
> allocate, free, kmap, etc. What pinning means and why you would need
> to do it, etc. What domains we support and what they are. What
> shadow bos are.
OK. For domains, I can create a separate change to add to "amdgpu_drm.h", in which they were defined.
For pinning/shadow bo, I can add it before the respective functions.
Sam
>
> Additional comments below for things to add or clarify to enhance the
> documentation.
>
>> ---
>> drivers/gpu/drm/amd/amdgpu/amdgpu_object.c | 233 +++++++++++++++++++++++++++++
>> 1 file changed, 233 insertions(+)
>>
>> diff --git a/drivers/gpu/drm/amd/amdgpu/amdgpu_object.c b/drivers/gpu/drm/amd/amdgpu/amdgpu_object.c
>> index 6a9e46a..271dbfa 100644
>> --- a/drivers/gpu/drm/amd/amdgpu/amdgpu_object.c
>> +++ b/drivers/gpu/drm/amd/amdgpu/amdgpu_object.c
>> @@ -73,6 +73,15 @@ static void amdgpu_ttm_bo_destroy(struct ttm_buffer_object *tbo)
>> kfree(bo);
>> }
>>
>> +/**
>> + * amdgpu_ttm_bo_is_amdgpu_bo - if the buffer object belongs to an &amdgpu_bo
>> + * @bo: buffer object to be checked
>> + *
>> + * Uses destroy function associated with the object to determine if this is
>> + * &amdgpu_bo.
>> + *
>> + * Returns true if the object belongs to &amdgpu_bo, false if not.
>> + */
>
> Just to clarify, it checks whether a ttm bo is an amdgpu buffer object or not.
>
>> bool amdgpu_ttm_bo_is_amdgpu_bo(struct ttm_buffer_object *bo)
>> {
>> if (bo->destroy == &amdgpu_ttm_bo_destroy)
>> @@ -80,6 +89,14 @@ bool amdgpu_ttm_bo_is_amdgpu_bo(struct ttm_buffer_object *bo)
>> return false;
>> }
>>
>> +/**
>> + * amdgpu_ttm_placement_from_domain - set buffer's placement
>> + * @abo: &amdgpu_bo buffer object whose placement is to be set
>> + * @domain: requested domain
>> + *
>> + * Sets buffer's placement according to requested domain and the buffer's
>> + * flags.
>> + */
>> void amdgpu_ttm_placement_from_domain(struct amdgpu_bo *abo, u32 domain)
>> {
>> struct amdgpu_device *adev = amdgpu_ttm_adev(abo->tbo.bdev);
>> @@ -498,6 +515,17 @@ static int amdgpu_bo_create_shadow(struct amdgpu_device *adev,
>> return r;
>> }
>>
>> +/**
>> + * amdgpu_bo_create - create an &amdgpu_bo buffer object
>> + * @adev: amdgpu device object
>> + * @bp: parameters to be used for the buffer object
>> + * @bo_ptr: pointer to the buffer object pointer
>> + *
>> + * Creates an &amdgpu_bo buffer object; and if requested, also creates a
>> + * shadow object.
>> + *
>> + * Returns 0 for success or a negative error code on failure.
>> + */
>> int amdgpu_bo_create(struct amdgpu_device *adev,
>> struct amdgpu_bo_param *bp,
>> struct amdgpu_bo **bo_ptr)
>> @@ -527,6 +555,20 @@ int amdgpu_bo_create(struct amdgpu_device *adev,
>> return r;
>> }
>>
>> +/**
>> + * amdgpu_bo_backup_to_shadow - Backs up an &amdgpu_bo buffer object
>> + * @adev: amdgpu device object
>> + * @ring: amdgpu_ring for the engine handling the buffer operations
>> + * @bo: &amdgpu_bo buffer to be backed up
>> + * @resv: reservation object with embedded fence
>> + * @fence: dma_fence associated with the operation
>> + * @direct: whether to submit the job directly
>> + *
>> + * 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.
>> + */
>> int amdgpu_bo_backup_to_shadow(struct amdgpu_device *adev,
>> struct amdgpu_ring *ring,
>> struct amdgpu_bo *bo,
>> @@ -559,6 +601,15 @@ int amdgpu_bo_backup_to_shadow(struct amdgpu_device *adev,
>> return r;
>> }
>>
>> +/**
>> + * amdgpu_bo_validate - validate an &amdgpu_bo buffer object
>> + * @bo: pointer to the buffer object
>> + *
>> + * Sets placement according to domain; and changes placement and caching
>> + * policy of the buffer object according to the placement.
>> + *
>> + * Returns 0 for success or a negative error code on failure.
>> + */
>
> This is used for validating shadow bos. Also worth mentioning that it
> calls ttm_bo_validate() which will make sure the buffer is resident
> where it needs to be.
>
>> int amdgpu_bo_validate(struct amdgpu_bo *bo)
>> {
>> struct ttm_operation_ctx ctx = { false, false };
>> @@ -581,6 +632,19 @@ int amdgpu_bo_validate(struct amdgpu_bo *bo)
>> return r;
>> }
>>
>> +/**
>> + * amdgpu_bo_restore_from_shadow - restore an &amdgpu_bo buffer object
>> + * @adev: amdgpu device object
>> + * @ring: amdgpu_ring for the engine handling the buffer operations
>> + * @bo: &amdgpu_bo buffer to be restored
>> + * @resv: reservation object with embedded fence
>> + * @fence: dma_fence associated with the operation
>> + * @direct: whether to submit the job directly
>> + *
>> + * Copies a buffer object's shadow content back to the object.
>> + *
>
> Mention that this is used for recovering a buffer from it's shadow in
> the case of a gpu reset where vram context may be lost.
>
>
>> + * 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,
>> struct amdgpu_bo *bo,
>> @@ -613,6 +677,16 @@ int amdgpu_bo_restore_from_shadow(struct amdgpu_device *adev,
>> return r;
>> }
>>
>> +/**
>> + * amdgpu_bo_kmap - map an &amdgpu_bo buffer object
>> + * @bo: &amdgpu_bo buffer object to be mapped
>> + * @ptr: kernel virtual address to be returned
>> + *
>> + * 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.
>> + */
>> int amdgpu_bo_kmap(struct amdgpu_bo *bo, void **ptr)
>> {
>> void *kptr;
>> @@ -643,6 +717,14 @@ int amdgpu_bo_kmap(struct amdgpu_bo *bo, void **ptr)
>> return 0;
>> }
>>
>> +/**
>> + * amdgpu_bo_kptr - returns a kernel virtual address of the buffer object
>> + * @bo: &amdgpu_bo buffer object
>> + *
>> + * Calls ttm_kmap_obj_virtual() to get the kernel virtual address
>> + *
>> + * Returns the virtual address of a buffer object area.
>> + */
>> void *amdgpu_bo_kptr(struct amdgpu_bo *bo)
>> {
>> bool is_iomem;
>> @@ -650,12 +732,26 @@ void *amdgpu_bo_kptr(struct amdgpu_bo *bo)
>> return ttm_kmap_obj_virtual(&bo->kmap, &is_iomem);
>> }
>>
>> +/**
>> + * amdgpu_bo_kunmap - unmap an &amdgpu_bo buffer object
>> + * @bo: &amdgpu_bo buffer object to be unmapped
>> + *
>> + * Unmaps a kernel map set up by amdgpu_bo_kmap().
>> + */
>> void amdgpu_bo_kunmap(struct amdgpu_bo *bo)
>> {
>> if (bo->kmap.bo)
>> ttm_bo_kunmap(&bo->kmap);
>> }
>>
>> +/**
>> + * amdgpu_bo_ref - reference an &amdgpu_bo buffer object
>> + * @bo: &amdgpu_bo buffer object
>> + *
>> + * References the contained &ttm_buffer_object.
>> + *
>> + * Returns a refcounted pointer to the &amdgpu_bo buffer object.
>> + */
>> struct amdgpu_bo *amdgpu_bo_ref(struct amdgpu_bo *bo)
>> {
>> if (bo == NULL)
>> @@ -665,6 +761,12 @@ struct amdgpu_bo *amdgpu_bo_ref(struct amdgpu_bo *bo)
>> return bo;
>> }
>>
>> +/**
>> + * amdgpu_bo_unref - unreference an &amdgpu_bo buffer object
>> + * @bo: &amdgpu_bo buffer object
>> + *
>> + * Unreferences the contained &ttm_buffer_object and clear the pointer
>> + */
>> void amdgpu_bo_unref(struct amdgpu_bo **bo)
>> {
>> struct ttm_buffer_object *tbo;
>> @@ -678,6 +780,20 @@ void amdgpu_bo_unref(struct amdgpu_bo **bo)
>> *bo = NULL;
>> }
>>
>> +/**
>> + * amdgpu_bo_pin_restricted - pin an &amdgpu_bo buffer object
>> + * @bo: &amdgpu_bo buffer object to be pinned
>> + * @domain: domain to be pinned to
>> + * @min_offset: the start of requested address range
>> + * @max_offset: the end of requested address range
>> + * @gpu_addr: GPU offset of the &amdgpu_bo buffer object
>> + *
>> + * Pins the buffer object according to requested domain and address range. If
>> + * the memory is unbinded gart memory, binds the pages into gart table. Adjusts
>
> unbinded ->unbound
>
>> + * pin_count and pin size accordingly.
>
> Also mention that this function give you more flexibility on where to
> pin a buffer is there are specific restrictions on where a buffer must
> be located. E.g., to meet certain hw requirements.
>
>> + *
>> + * 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,
>> u64 *gpu_addr)
>> @@ -776,11 +892,30 @@ int amdgpu_bo_pin_restricted(struct amdgpu_bo *bo, u32 domain,
>> return r;
>> }
>>
>> +/**
>> + * amdgpu_bo_pin - pin an &amdgpu_bo buffer object
>> + * @bo: &amdgpu_bo buffer object to be pinned
>> + * @domain: domain to be pinned to
>> + * @gpu_addr: GPU offset of the &amdgpu_bo buffer object
>> + *
>> + * A simple wrapper to amdgpu_bo_pin_restricted().
>
> 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.
>> + */
>> int amdgpu_bo_pin(struct amdgpu_bo *bo, u32 domain, u64 *gpu_addr)
>> {
>> return amdgpu_bo_pin_restricted(bo, domain, 0, 0, gpu_addr);
>> }
>>
>> +/**
>> + * amdgpu_bo_unpin - unpin an &amdgpu_bo buffer object
>> + * @bo: &amdgpu_bo buffer object to be unpinned
>> + *
>> + * 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.
>> + */
>> int amdgpu_bo_unpin(struct amdgpu_bo *bo)
>> {
>> struct amdgpu_device *adev = amdgpu_ttm_adev(bo->tbo.bdev);
>> @@ -816,6 +951,14 @@ int amdgpu_bo_unpin(struct amdgpu_bo *bo)
>> return r;
>> }
>>
>> +/**
>> + * amdgpu_bo_evict_vram - evict VRAM buffers
>> + * @adev: amdgpu device object
>> + *
>> + * 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.
>> + */
>> int amdgpu_bo_evict_vram(struct amdgpu_device *adev)
>> {
>> /* late 2.6.33 fix IGP hibernate - we need pm ops to do this correct */
>> @@ -838,6 +981,14 @@ static const char *amdgpu_vram_names[] = {
>> "DDR4",
>> };
>>
>> +/**
>> + * amdgpu_bo_init - initialize memory manager
>> + * @adev: amdgpu device object
>> + *
>> + * Calls amdgpu_ttm_init() to initialize amdgpu memory manager.
>> + *
>> + * Returns 0 for success or a negative error code on failure.
>> + */
>> int amdgpu_bo_init(struct amdgpu_device *adev)
>> {
>> /* reserve PAT memory space to WC for VRAM */
>> @@ -855,6 +1006,15 @@ int amdgpu_bo_init(struct amdgpu_device *adev)
>> return amdgpu_ttm_init(adev);
>> }
>>
>> +/**
>> + * amdgpu_bo_late_init - late init
>> + * @adev: amdgpu device object
>> + *
>> + * Calls amdgpu_ttm_late_init() to free resources used earlier during
>> + * initialization.
>> + *
>> + * Returns 0 for success or a negative error code on failure.
>> + */
>> int amdgpu_bo_late_init(struct amdgpu_device *adev)
>> {
>> amdgpu_ttm_late_init(adev);
>> @@ -862,6 +1022,12 @@ int amdgpu_bo_late_init(struct amdgpu_device *adev)
>> return 0;
>> }
>>
>> +/**
>> + * amdgpu_bo_fini - tear down memory manager
>> + * @adev: amdgpu device object
>> + *
>> + * Reverses amdgpu_bo_init() to tear down memory manager.
>> + */
>> void amdgpu_bo_fini(struct amdgpu_device *adev)
>> {
>> amdgpu_ttm_fini(adev);
>> @@ -869,12 +1035,30 @@ void amdgpu_bo_fini(struct amdgpu_device *adev)
>> arch_io_free_memtype_wc(adev->gmc.aper_base, adev->gmc.aper_size);
>> }
>>
>> +/**
>> + * amdgpu_bo_fbdev_mmap - mmap fbdev memory
>> + * @bo: &amdgpu_bo buffer object
>> + * @vma: vma as input from the fbdev mmap method
>> + *
>> + * 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.
>> + */
>> int amdgpu_bo_fbdev_mmap(struct amdgpu_bo *bo,
>> struct vm_area_struct *vma)
>> {
>> return ttm_fbdev_mmap(vma, &bo->tbo);
>> }
>>
>> +/**
>> + * amdgpu_bo_set_tiling_flags - set tiling flags
>> + * @bo: &amdgpu_bo buffer object
>> + * @tiling_flags: new flags
>> + *
>> + * Sets buffer object's tiling flags with the new one.
>> + *
>
> Used to via GEM ioctl to set the tiling flags on a buffer.
>
>> + * Returns 0 for success or a negative error code on failure.
>> + */
>> int amdgpu_bo_set_tiling_flags(struct amdgpu_bo *bo, u64 tiling_flags)
>> {
>> struct amdgpu_device *adev = amdgpu_ttm_adev(bo->tbo.bdev);
>> @@ -887,6 +1071,13 @@ int amdgpu_bo_set_tiling_flags(struct amdgpu_bo *bo, u64 tiling_flags)
>> return 0;
>> }
>>
>> +/**
>> + * amdgpu_bo_get_tiling_flags - get tiling flags
>> + * @bo: &amdgpu_bo buffer object
>> + * @tiling_flags: returned flags
>> + *
>> + * Gets buffer object's tiling flags.
>
> Used to via GEM ioctl to get the tiling flags on a buffer.
>
>> + */
>> void amdgpu_bo_get_tiling_flags(struct amdgpu_bo *bo, u64 *tiling_flags)
>> {
>> lockdep_assert_held(&bo->tbo.resv->lock.base);
>> @@ -895,6 +1086,17 @@ void amdgpu_bo_get_tiling_flags(struct amdgpu_bo *bo, u64 *tiling_flags)
>> *tiling_flags = bo->tiling_flags;
>> }
>>
>> +/**
>> + * amdgpu_bo_set_metadata - set metadata
>> + * @bo: &amdgpu_bo buffer object
>> + * @metadata: new metadata
>> + * @metadata_size: size of the new metadata
>> + * @flags: flags of the new metadata
>> + *
>> + * Sets buffer object's metadata, its size and flags
>
> Used to via GEM ioctl to set the metadata on a buffer.
>
>> + *
>> + * 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)
>> {
>> @@ -924,6 +1126,19 @@ int amdgpu_bo_set_metadata (struct amdgpu_bo *bo, void *metadata,
>> return 0;
>> }
>>
>> +/**
>> + * amdgpu_bo_get_metadata - get metadata
>> + * @bo: &amdgpu_bo buffer object
>> + * @buffer: returned metadata
>> + * @buffer_size: size of the buffer
>> + * @metadata_size: size of the returned metadata
>> + * @flags: flags of the returned metadata
>> + *
>> + * Gets buffer object's metadata, its size and flags. buffer_size shall not be
>> + * less than metadata_size.
>
> Used to via GEM ioctl to get the metadata on a buffer.
>
>> + *
>> + * 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,
>> uint64_t *flags)
>> @@ -947,6 +1162,15 @@ int amdgpu_bo_get_metadata(struct amdgpu_bo *bo, void *buffer,
>> return 0;
>> }
>>
>> +/**
>> + * amdgpu_bo_move_notify - notification about a memory move
>> + * @bo: pointer to a buffer object
>> + * @evict: if this move is evicting the buffer from the graphics address space
>> + * @new_mem: new information of the bufer object
>> + *
>> + * Marks the corresponding &amdgpu_bo buffer object as invalid, also performs
>> + * bookkeeping.
>
> ttm driver callback which is called when ttm moves a buffer.
>
>> + */
>> void amdgpu_bo_move_notify(struct ttm_buffer_object *bo,
>> bool evict,
>> struct ttm_mem_reg *new_mem)
>> @@ -975,6 +1199,15 @@ void amdgpu_bo_move_notify(struct ttm_buffer_object *bo,
>> trace_amdgpu_ttm_bo_move(abo, new_mem->mem_type, old_mem->mem_type);
>> }
>>
>> +/**
>> + * amdgpu_bo_fault_reserve_notify - notification about a memory fault
>> + * @bo: pointer to a buffer object
>> + *
>> + * Notifies the driver we are taking a fault on this BO and have reserved it,
>> + * also performs bookkeeping.
>> + *
>
> ttm driver callback for dealing with vm faults.
>
>> + * Returns 0 for success or a negative error code on failure.
>> + */
>> int amdgpu_bo_fault_reserve_notify(struct ttm_buffer_object *bo)
>> {
>> struct amdgpu_device *adev = amdgpu_ttm_adev(bo->bdev);
>> --
>> 2.7.4
>>
>> _______________________________________________
>> amd-gfx mailing list
>> amd-gfx at lists.freedesktop.org
>> https://lists.freedesktop.org/mailman/listinfo/amd-gfx
More information about the amd-gfx
mailing list