We're moving to Sphinx style documentation. Conver the comments to that format. Also document some new content. Signed-off-by: Tom St Denis <tom.stdenis at amd.com> --- drivers/gpu/drm/amd/amdgpu/amdgpu_ttm.c | 254 +++++++++++++++++++++++--------- 1 file changed, 185 insertions(+), 69 deletions(-) diff --git a/drivers/gpu/drm/amd/amdgpu/amdgpu_ttm.c b/drivers/gpu/drm/amd/amdgpu/amdgpu_ttm.c index 57d4da6bdbe4..367d5bc2630f 100644 --- a/drivers/gpu/drm/amd/amdgpu/amdgpu_ttm.c +++ b/drivers/gpu/drm/amd/amdgpu/amdgpu_ttm.c @@ -65,8 +65,9 @@ static void amdgpu_ttm_debugfs_fini(struct amdgpu_device *adev); */ /** - * amdgpu_ttm_mem_global_init - Initialize and acquire reference to - * memory object + * DOC: amdgpu_ttm_mem_global_init + * + * Initialize and acquire reference to memory object * * @ref: Object for initialization. * @@ -79,7 +80,9 @@ static int amdgpu_ttm_mem_global_init(struct drm_global_reference *ref) } /** - * amdgpu_ttm_mem_global_release - Drop reference to a memory object + * DOC: amdgpu_ttm_mem_global_release + * + * Drop reference to a memory object * * @ref: Object being removed * @@ -92,8 +95,9 @@ static void amdgpu_ttm_mem_global_release(struct drm_global_reference *ref) } /** - * amdgpu_ttm_global_init - Initialize global TTM memory reference - * structures. + * DOC: amdgpu_ttm_global_init + * + * Initialize global TTM memory reference structures. * * @adev: AMDGPU device for which the global structures need to be * registered. @@ -177,8 +181,9 @@ static int amdgpu_invalidate_caches(struct ttm_bo_device *bdev, uint32_t flags) } /** - * amdgpu_init_mem_type - Initialize a memory manager for a specific - * type of memory request. + * DOC: amdgpu_init_mem_type + * + * Initialize a memory manager for a specific type of memory request. * * @bdev: The TTM BO device object (contains a reference to * amdgpu_device) @@ -237,12 +242,14 @@ static int amdgpu_init_mem_type(struct ttm_bo_device *bdev, uint32_t type, } /** - * amdgpu_evict_flags - Compute placement flags + * DOC: amdgpu_evict_flags + * + * Compute placement flags * * @bo: The buffer object to evict * @placement: Possible destination(s) for evicted BO * - * Fill in placement data when ttm_bo_evict() is called + * Fill in placement data when ttm_bo_evict() is called. */ static void amdgpu_evict_flags(struct ttm_buffer_object *bo, struct ttm_placement *placement) @@ -305,7 +312,9 @@ static void amdgpu_evict_flags(struct ttm_buffer_object *bo, } /** - * amdgpu_verify_access - Verify access for a mmap call + * DOC: amdgpu_verify_access + * + * Verify access for a mmap call * * @bo: The buffer object to map * @filp: The file pointer from the process performing the mmap @@ -331,7 +340,9 @@ static int amdgpu_verify_access(struct ttm_buffer_object *bo, struct file *filp) } /** - * amdgpu_move_null - Register memory for a buffer object + * DOC: amdgpu_move_null + * + * Register memory for a buffer object * * @bo: The bo to assign the memory to * @new_mem: The memory to be assigned. @@ -350,8 +361,9 @@ static void amdgpu_move_null(struct ttm_buffer_object *bo, } /** - * amdgpu_mm_node_addr - Compute the GPU relative offset of a GTT - * buffer. + * DOC: amdgpu_mm_node_addr + * + * Compute the GPU relative offset of a GTT buffer. */ static uint64_t amdgpu_mm_node_addr(struct ttm_buffer_object *bo, struct drm_mm_node *mm_node, @@ -367,10 +379,10 @@ static uint64_t amdgpu_mm_node_addr(struct ttm_buffer_object *bo, } /** - * amdgpu_find_mm_node - Helper function finds the drm_mm_node - * corresponding to @offset. It also modifies - * the offset to be within the drm_mm_node - * returned + * DOC: amdgpu_find_mm_node + * + * Helper function finds the drm_mm_node corresponding to @offset. It + * also modifies the offset to be within the drm_mm_node returned. */ static struct drm_mm_node *amdgpu_find_mm_node(struct ttm_mem_reg *mem, unsigned long *offset) @@ -385,7 +397,9 @@ static struct drm_mm_node *amdgpu_find_mm_node(struct ttm_mem_reg *mem, } /** - * amdgpu_copy_ttm_mem_to_mem - Helper function for copy + * DOC: amdgpu_copy_ttm_mem_to_mem + * + * Helper function for copy * * The function copies @size bytes from {src->mem + src->offset} to * {dst->mem + dst->offset}. src->bo and dst->bo could be same BO for a @@ -510,7 +524,9 @@ int amdgpu_ttm_copy_mem_to_mem(struct amdgpu_device *adev, } /** - * amdgpu_move_blit - Copy an entire buffer to another buffer + * DOC: amdgpu_move_blit + * + * Copy an entire buffer to another buffer * * This is a helper called by amdgpu_bo_move() and * amdgpu_move_vram_ram() to help move buffers to and from VRAM. @@ -550,7 +566,9 @@ static int amdgpu_move_blit(struct ttm_buffer_object *bo, } /** - * amdgpu_move_vram_ram - Copy VRAM buffer to RAM buffer + * DOC: amdgpu_move_vram_ram + * + * Copy VRAM buffer to RAM buffer * * Called by amdgpu_bo_move(). */ @@ -608,7 +626,9 @@ static int amdgpu_move_vram_ram(struct ttm_buffer_object *bo, bool evict, } /** - * amdgpu_move_ram_vram - Copy buffer from RAM to VRAM + * DOC: amdgpu_move_ram_vram + * + * Copy buffer from RAM to VRAM * * Called by amdgpu_bo_move(). */ @@ -657,7 +677,9 @@ static int amdgpu_move_ram_vram(struct ttm_buffer_object *bo, bool evict, } /** - * amdgpu_bo_move - Move a buffer object to a new memory location + * DOC: amdgpu_bo_move + * + * Move a buffer object to a new memory location * * Called by ttm_bo_handle_move_mem() */ @@ -727,7 +749,9 @@ static int amdgpu_bo_move(struct ttm_buffer_object *bo, bool evict, } /** - * amdgpu_ttm_io_mem_reserve - Reserve a block of memory during a fault + * DOC: amdgpu_ttm_io_mem_reserve + * + * Reserve a block of memory during a fault * * Called by ttm_mem_io_reserve() ultimately via ttm_bo_vm_fault() */ @@ -809,8 +833,9 @@ struct amdgpu_ttm_tt { }; /** - * amdgpu_ttm_tt_get_user_pages - Pin pages of memory pointed to - * by a USERPTR pointer to memory + * DOC: amdgpu_ttm_tt_get_user_pages + * + * Grab a reference to pages of memory pointed to by a USERPTR pointer * * Called by amdgpu_gem_userptr_ioctl() and amdgpu_cs_parser_bos(). * This provides a wrapper around the get_user_pages() call to provide @@ -876,8 +901,9 @@ int amdgpu_ttm_tt_get_user_pages(struct ttm_tt *ttm, struct page **pages) } /** - * amdgpu_ttm_tt_set_user_pages - Copy pages in, putting old pages - * as necessary. + * DOC: amdgpu_ttm_tt_set_user_pages + * + * Copy pages in, putting old pages as necessary. * * Called by amdgpu_cs_list_validate(). This creates the page list * that backs user memory and will ultimately be mapped into the device @@ -898,7 +924,9 @@ void amdgpu_ttm_tt_set_user_pages(struct ttm_tt *ttm, struct page **pages) } /** - * amdgpu_ttm_tt_mark_user_page - Mark pages as dirty + * DOC: amdgpu_ttm_tt_mark_user_page + * + * Mark pages as dirty * * Called while unpinning userptr pages */ @@ -921,8 +949,9 @@ void amdgpu_ttm_tt_mark_user_pages(struct ttm_tt *ttm) } /** - * amdgpu_ttm_tt_pin_userptr - prepare the sg table with the - * user pages + * DOC: amdgpu_ttm_tt_pin_userptr + * + * prepare the sg table with the user pages * * Called by amdgpu_ttm_backend_bind() **/ @@ -962,7 +991,9 @@ static int amdgpu_ttm_tt_pin_userptr(struct ttm_tt *ttm) } /** - * amdgpu_ttm_tt_unpin_userptr - Unpin and unmap userptr pages + * DOC: amdgpu_ttm_tt_unpin_userptr + * + * Unpin and unmap userptr pages */ static void amdgpu_ttm_tt_unpin_userptr(struct ttm_tt *ttm) { @@ -986,6 +1017,12 @@ static void amdgpu_ttm_tt_unpin_userptr(struct ttm_tt *ttm) sg_free_table(ttm->sg); } +/** + * DOC: amdgpu_ttm_gart_bind + * + * Wrapper for amdgpu_gart_bind() to handle GFX9 specific page + * mappings. + */ int amdgpu_ttm_gart_bind(struct amdgpu_device *adev, struct ttm_buffer_object *tbo, uint64_t flags) @@ -995,6 +1032,10 @@ int amdgpu_ttm_gart_bind(struct amdgpu_device *adev, struct amdgpu_ttm_tt *gtt = (void *)ttm; int r; + /* for a MQD buffer object map the first + * page as is. For all subsequent pages map them as + * an MTYPE of NC. + */ if (abo->flags & AMDGPU_GEM_CREATE_MQD_GFX9) { uint64_t page_idx = 1; @@ -1013,6 +1054,7 @@ int amdgpu_ttm_gart_bind(struct amdgpu_device *adev, &ttm->pages[page_idx], &(gtt->ttm.dma_address[page_idx]), flags); } else { + /* fall back to a regular gart binding */ r = amdgpu_gart_bind(adev, gtt->offset, ttm->num_pages, ttm->pages, gtt->ttm.dma_address, flags); } @@ -1026,7 +1068,9 @@ int amdgpu_ttm_gart_bind(struct amdgpu_device *adev, } /** - * amdgpu_ttm_backend_bind - Bind GTT memory + * DOC: amdgpu_ttm_backend_bind + * + * Bind GTT memory * * Called by ttm_tt_bind() on behalf of ttm_bo_handle_move_mem(). * This handles binding GTT memory to the device address space. @@ -1076,7 +1120,9 @@ static int amdgpu_ttm_backend_bind(struct ttm_tt *ttm, } /** - * amdgpu_ttm_alloc_gart - Allocate GART memory for buffer object + * DOC: amdgpu_ttm_alloc_gart + * + * Allocate GART memory for buffer object */ int amdgpu_ttm_alloc_gart(struct ttm_buffer_object *bo) { @@ -1129,7 +1175,9 @@ int amdgpu_ttm_alloc_gart(struct ttm_buffer_object *bo) } /** - * amdgpu_ttm_recover_gart - Rebind GTT pages + * DOC: amdgpu_ttm_recover_gart + * + * Rebind GTT pages * * Called by amdgpu_gtt_mgr_recover() from amdgpu_device_reset() to * rebind GTT pages during a GPU reset. @@ -1150,7 +1198,9 @@ int amdgpu_ttm_recover_gart(struct ttm_buffer_object *tbo) } /** - * amdgpu_ttm_backend_unbind - Unbind GTT mapped pages + * DOC: amdgpu_ttm_backend_unbind + * + * Unbind GTT mapped pages * * Called by ttm_tt_unbind() on behalf of ttm_bo_move_ttm() and * ttm_tt_destroy(). @@ -1191,7 +1241,9 @@ static struct ttm_backend_func amdgpu_backend_func = { }; /** - * amdgpu_ttm_tt_create - Create a ttm_tt object for a given BO + * DOC: amdgpu_ttm_tt_create + * + * Create a ttm_tt object for a given BO * * @bo: The buffer object to create a GTT ttm_tt object around * @@ -1220,7 +1272,9 @@ static struct ttm_tt *amdgpu_ttm_tt_create(struct ttm_buffer_object *bo, } /** - * amdgpu_ttm_tt_populate - Map GTT pages visible to the device + * DOC: amdgpu_ttm_tt_populate + * + * Map GTT pages visible to the device * * Map the pages of a ttm_tt object to an address space visible * to the underlying device. @@ -1263,7 +1317,9 @@ static int amdgpu_ttm_tt_populate(struct ttm_tt *ttm, } /** - * amdgpu_ttm_tt_unpopulate - unmap GTT pages and unpopulate page arrays + * DOC: amdgpu_ttm_tt_unpopulate + * + * Unmap GTT pages and unpopulate page arrays * * Unmaps pages of a ttm_tt object from the device address space and * unpopulates the page array backing it. @@ -1298,8 +1354,9 @@ static void amdgpu_ttm_tt_unpopulate(struct ttm_tt *ttm) } /** - * amdgpu_ttm_tt_set_userptr - Initialize userptr GTT ttm_tt - * for the current task + * DOC: amdgpu_ttm_tt_set_userptr + * + * Initialize userptr GTT ttm_tt for the current task * * @ttm: The ttm_tt object to bind this userptr object to * @addr: The address in the current tasks VM space to use @@ -1328,7 +1385,9 @@ int amdgpu_ttm_tt_set_userptr(struct ttm_tt *ttm, uint64_t addr, } /** - * amdgpu_ttm_tt_get_usermm - Return memory manager for ttm_tt object + * DOC: amdgpu_ttm_tt_get_usermm + * + * Return memory manager for ttm_tt object */ struct mm_struct *amdgpu_ttm_tt_get_usermm(struct ttm_tt *ttm) { @@ -1341,9 +1400,10 @@ struct mm_struct *amdgpu_ttm_tt_get_usermm(struct ttm_tt *ttm) } /** - * amdgpu_ttm_tt_affect_userptr - Determine if a ttm_tt object lays - * inside an address range for the - * current task. + * DOC: amdgpu_ttm_tt_affect_userptr + * + * Determine if a ttm_tt object lays inside an address range for the + * current task. * */ bool amdgpu_ttm_tt_affect_userptr(struct ttm_tt *ttm, unsigned long start, @@ -1381,8 +1441,9 @@ bool amdgpu_ttm_tt_affect_userptr(struct ttm_tt *ttm, unsigned long start, } /** - * amdgpu_ttm_tt_userptr_invalidated - Has the ttm_tt object been - * invalidated? + * DOC: amdgpu_ttm_tt_userptr_invalidated + * + * Has the ttm_tt object been invalidated? */ bool amdgpu_ttm_tt_userptr_invalidated(struct ttm_tt *ttm, int *last_invalidated) @@ -1395,10 +1456,10 @@ bool amdgpu_ttm_tt_userptr_invalidated(struct ttm_tt *ttm, } /** - * amdgpu_ttm_tt_userptr_needs_pages - Have the pages backing this - * ttm_tt object been invalidated - * since the last time they've - * been set? + * DOC: amdgpu_ttm_tt_userptr_needs_pages + * + * Have the pages backing this ttm_tt object been invalidated + * since the last time they've been set? */ bool amdgpu_ttm_tt_userptr_needs_pages(struct ttm_tt *ttm) { @@ -1411,7 +1472,9 @@ bool amdgpu_ttm_tt_userptr_needs_pages(struct ttm_tt *ttm) } /** - * amdgpu_ttm_tt_is_readonly - Is the ttm_tt object read only? + * DOC: amdgpu_ttm_tt_is_readonly + * + * Is the ttm_tt object read only? */ bool amdgpu_ttm_tt_is_readonly(struct ttm_tt *ttm) { @@ -1424,7 +1487,9 @@ bool amdgpu_ttm_tt_is_readonly(struct ttm_tt *ttm) } /** - * amdgpu_ttm_tt_pte_flags - Compute PTE flags for ttm_tt object + * DOC: amdgpu_ttm_tt_pte_flags + * + * Compute PTE flags for ttm_tt object * * @ttm: The ttm_tt object to compute the flags for * @mem: The memory registry backing this ttm_tt object @@ -1454,8 +1519,9 @@ uint64_t amdgpu_ttm_tt_pte_flags(struct amdgpu_device *adev, struct ttm_tt *ttm, } /** - * amdgpu_ttm_bo_eviction_valuable - Check to see if we can evict - * a buffer object. + * DOC: amdgpu_ttm_bo_eviction_valuable + * + * Check to see if we can evict a buffer object. * * Return true if eviction is sensible. Called by * ttm_mem_evict_first() on behalf of ttm_bo_mem_force_space() @@ -1510,8 +1576,9 @@ static bool amdgpu_ttm_bo_eviction_valuable(struct ttm_buffer_object *bo, } /** - * amdgpu_ttm_access_memory - Read or Write memory that backs a - * buffer object. + * DOC: amdgpu_ttm_access_memory + * + * Read or Write memory that backs a buffer object. * * @bo: The buffer object to read/write * @offset: Offset into buffer object @@ -1602,7 +1669,9 @@ static struct ttm_bo_driver amdgpu_bo_driver = { * Firmware Reservation functions */ /** - * amdgpu_ttm_fw_reserve_vram_fini - free fw reserved vram + * DOC: amdgpu_ttm_fw_reserve_vram_fini + * + * free fw reserved vram * * @adev: amdgpu_device pointer * @@ -1615,7 +1684,9 @@ static void amdgpu_ttm_fw_reserve_vram_fini(struct amdgpu_device *adev) } /** - * amdgpu_ttm_fw_reserve_vram_init - create bo vram reservation from fw + * DOC: amdgpu_ttm_fw_reserve_vram_init + * + * create bo vram reservation from fw * * @adev: amdgpu_device pointer * @@ -1699,8 +1770,10 @@ static int amdgpu_ttm_fw_reserve_vram_init(struct amdgpu_device *adev) return r; } /** - * amdgpu_ttm_init - Init the memory management (ttm) as well as - * various gtt/vram related fields. + * DOC: amdgpu_ttm_init + * + * Init the memory management (ttm) as well as various gtt/vram + * related fields. * * This initializes all of the memory space pools that the TTM layer * will need such as the GTT space (system memory mapped to the device), @@ -1851,8 +1924,9 @@ int amdgpu_ttm_init(struct amdgpu_device *adev) } /** - * amdgpu_ttm_late_init - Handle any late initialization for - * amdgpu_ttm + * DOC: amdgpu_ttm_late_init + * + * Handle any late initialization for amdgpu_ttm */ void amdgpu_ttm_late_init(struct amdgpu_device *adev) { @@ -1861,7 +1935,9 @@ void amdgpu_ttm_late_init(struct amdgpu_device *adev) } /** - * amdgpu_ttm_fini - De-initialize the TTM memory pools + * DOC: amdgpu_ttm_fini + * + * De-initialize the TTM memory pools */ void amdgpu_ttm_fini(struct amdgpu_device *adev) { @@ -1889,7 +1965,9 @@ void amdgpu_ttm_fini(struct amdgpu_device *adev) } /** - * amdgpu_ttm_set_buffer_funcs_status - enable/disable use of buffer functions + * DOC: amdgpu_ttm_set_buffer_funcs_status + * + * enable/disable use of buffer functions * * @adev: amdgpu_device pointer * @enable: true when we can use buffer functions. @@ -1914,6 +1992,11 @@ void amdgpu_ttm_set_buffer_funcs_status(struct amdgpu_device *adev, bool enable) adev->mman.buffer_funcs_enabled = enable; } +/** + * DOC: amdgpu_mmap + * + * Wrapper to handle memory mapping buffer objects owned by amdgpu. + */ int amdgpu_mmap(struct file *filp, struct vm_area_struct *vma) { struct drm_file *file_priv; @@ -1930,6 +2013,13 @@ int amdgpu_mmap(struct file *filp, struct vm_area_struct *vma) return ttm_bo_mmap(filp, vma, &adev->mman.bdev); } +/** + * DOC: amdgpu_map_buffer + * + * Map a window of TTM_PL_TT memory types to GTT space if the buffer + * object isn't already mapped. Called by + * amdgpu_ttm_copy_mem_to_mem(). + */ static int amdgpu_map_buffer(struct ttm_buffer_object *bo, struct ttm_mem_reg *mem, unsigned num_pages, uint64_t offset, unsigned window, @@ -1996,6 +2086,17 @@ static int amdgpu_map_buffer(struct ttm_buffer_object *bo, return r; } +/** + * DOC: amdgpu_copy_buffer + * + * Use the SDMA to perform a copy from one offset to another. Called + * by amdgpu_copy_ttm_mem_to_mem() to finally copy windows of memory + * once they are mapped into GPU visible space. + * + * Also called by amdgpu_bo_backup_to_shadow() to backup a buffer + * object to shadow memory and vice versa with + * amdgpu_bo_restore_from_shadow(). + */ int amdgpu_copy_buffer(struct amdgpu_ring *ring, uint64_t src_offset, uint64_t dst_offset, uint32_t byte_count, struct reservation_object *resv, @@ -2072,6 +2173,11 @@ int amdgpu_copy_buffer(struct amdgpu_ring *ring, uint64_t src_offset, return r; } +/** + * DOC: amdgpu_fill_buffer + * + * Emit a linear fill operation. + */ int amdgpu_fill_buffer(struct amdgpu_bo *bo, uint32_t src_data, struct reservation_object *resv, @@ -2191,7 +2297,9 @@ static const struct drm_info_list amdgpu_ttm_debugfs_list[] = { }; /** - * amdgpu_ttm_vram_read - Linear read access to VRAM + * DOC: amdgpu_ttm_vram_read + * + * Linear read access to VRAM * * Accesses VRAM via MMIO for debugging purposes. */ @@ -2235,7 +2343,9 @@ static ssize_t amdgpu_ttm_vram_read(struct file *f, char __user *buf, } /** - * amdgpu_ttm_vram_write - Linear write access to VRAM + * DOC: amdgpu_ttm_vram_write + * + * Linear write access to VRAM * * Accesses VRAM via MMIO for debugging purposes. */ @@ -2288,7 +2398,9 @@ static const struct file_operations amdgpu_ttm_vram_fops = { #ifdef CONFIG_DRM_AMDGPU_GART_DEBUGFS /** - * amdgpu_ttm_gtt_read - Linear read access to GTT memory + * DOC: amdgpu_ttm_gtt_read + * + * Linear read access to GTT memory */ static ssize_t amdgpu_ttm_gtt_read(struct file *f, char __user *buf, size_t size, loff_t *pos) @@ -2338,7 +2450,9 @@ static const struct file_operations amdgpu_ttm_gtt_fops = { #endif /** - * amdgpu_iomem_read - Virtual read access to GPU mapped memory + * DOC: amdgpu_iomem_read + * + * Virtual read access to GPU mapped memory. * * This function is used to read memory that has been mapped to the * GPU and the known addresses are not physical addresses but instead @@ -2394,7 +2508,9 @@ static ssize_t amdgpu_iomem_read(struct file *f, char __user *buf, } /** - * amdgpu_iomem_write - Virtual write access to GPU mapped memory + * DOC: amdgpu_iomem_write + * + * Virtual write access to GPU mapped memory. * * This function is used to write memory that has been mapped to the * GPU and the known addresses are not physical addresses but instead -- 2.14.3