Add missing kernel-doc for DRM buddy allocator flags, drm_buddy_block, and drm_buddy. The documentation covers block header fields, allocator roots, free trees, and allocation flags such as RANGE, TOPDOWN, CONTIGUOUS, CLEAR, and TRIM_DISABLE. Private members are marked with kernel-doc private markers and documented with regular comments.
No functional changes. Cc: Christian König <[email protected]> Cc: Arunpravin Paneer Selvam <[email protected]> Suggested-by: Matthew Auld <[email protected]> Signed-off-by: Sanjay Yadav <[email protected]> --- include/drm/drm_buddy.h | 122 +++++++++++++++++++++++++++++++++------- 1 file changed, 102 insertions(+), 20 deletions(-) diff --git a/include/drm/drm_buddy.h b/include/drm/drm_buddy.h index eb8b4f5e15b3..5e2969822362 100644 --- a/include/drm/drm_buddy.h +++ b/include/drm/drm_buddy.h @@ -14,14 +14,81 @@ struct drm_printer; +/** + * DRM_BUDDY_RANGE_ALLOCATION - Allocate within a specific address range + * + * When set, allocation is restricted to the range [start, end) specified + * in drm_buddy_alloc_blocks(). Without this flag, start/end are ignored + * and allocation can use any free space. + */ #define DRM_BUDDY_RANGE_ALLOCATION BIT(0) + +/** + * DRM_BUDDY_TOPDOWN_ALLOCATION - Allocate from top of address space + * + * Allocate starting from high addresses and working down. Useful for + * separating different allocation types (e.g., kernel vs userspace) + * to reduce fragmentation. + */ #define DRM_BUDDY_TOPDOWN_ALLOCATION BIT(1) + +/** + * DRM_BUDDY_CONTIGUOUS_ALLOCATION - Require physically contiguous blocks + * + * The allocation must be satisfied with a single contiguous block. + * If the requested size cannot be allocated contiguously, the + * allocation fails with -ENOSPC. + */ #define DRM_BUDDY_CONTIGUOUS_ALLOCATION BIT(2) + +/** + * DRM_BUDDY_CLEAR_ALLOCATION - Prefer pre-cleared (zeroed) memory + * + * Attempt to allocate from the clear tree first. If insufficient clear + * memory is available, falls back to dirty memory. Useful when the + * caller needs zeroed memory and wants to avoid GPU clear operations. + */ #define DRM_BUDDY_CLEAR_ALLOCATION BIT(3) + +/** + * DRM_BUDDY_CLEARED - Mark returned blocks as cleared + * + * Used with drm_buddy_free_list() to indicate that the memory being + * freed has been cleared (zeroed). The blocks will be placed in the + * clear tree for future DRM_BUDDY_CLEAR_ALLOCATION requests. + */ #define DRM_BUDDY_CLEARED BIT(4) + +/** + * DRM_BUDDY_TRIM_DISABLE - Disable automatic block trimming + * + * By default, if an allocation is smaller than the allocated block, + * excess memory is trimmed and returned to the free pool. This flag + * disables trimming, keeping the full power-of-two block size. + */ #define DRM_BUDDY_TRIM_DISABLE BIT(5) +/** + * struct drm_buddy_block - Block within a buddy allocator + * + * Each block in the buddy allocator is represented by this structure. + * Blocks are organized in a binary tree where each parent block can be + * split into two children (left and right buddies). The allocator manages + * blocks at various orders (power-of-2 sizes) from chunk_size up to the + * largest contiguous region. + * + * @private: Private data owned by the allocator user (e.g., driver-specific data) + * @link: List node for user ownership while block is allocated + */ struct drm_buddy_block { +/* private: */ + /* + * Header bit layout: + * - Bits 63:12: block offset within the address space + * - Bits 11:10: state (ALLOCATED, FREE, or SPLIT) + * - Bit 9: clear bit (1 if memory is zeroed) + * - Bits 5:0: order (log2 of size relative to chunk_size) + */ #define DRM_BUDDY_HEADER_OFFSET GENMASK_ULL(63, 12) #define DRM_BUDDY_HEADER_STATE GENMASK_ULL(11, 10) #define DRM_BUDDY_ALLOCATED (1 << 10) @@ -36,7 +103,7 @@ struct drm_buddy_block { struct drm_buddy_block *left; struct drm_buddy_block *right; struct drm_buddy_block *parent; - +/* public: */ void *private; /* owned by creator */ /* @@ -46,43 +113,58 @@ struct drm_buddy_block { * drm_buddy_free* ownership is given back to the mm. */ union { +/* private: */ struct rb_node rb; +/* public: */ struct list_head link; }; - +/* private: */ struct list_head tmp_link; }; /* Order-zero must be at least SZ_4K */ #define DRM_BUDDY_MAX_ORDER (63 - 12) -/* - * Binary Buddy System. +/** + * struct drm_buddy - DRM binary buddy allocator + * + * The buddy allocator provides efficient power-of-two memory allocation + * with fast allocation and free operations. It is commonly used for GPU + * memory management where allocations can be split into power-of-two + * block sizes. * - * Locking should be handled by the user, a simple mutex around - * drm_buddy_alloc* and drm_buddy_free* should suffice. + * Locking should be handled by the user; a simple mutex around + * drm_buddy_alloc_blocks() and drm_buddy_free_block()/drm_buddy_free_list() + * should suffice. + * + * @n_roots: Number of root blocks in the roots array. + * @max_order: Maximum block order (log2 of largest block size / chunk_size). + * @chunk_size: Minimum allocation granularity in bytes. Must be at least SZ_4K. + * @size: Total size of the address space managed by this allocator in bytes. + * @avail: Total free space currently available for allocation in bytes. + * @clear_avail: Free space available in the clear tree (zeroed memory) in bytes. + * This is a subset of @avail. */ struct drm_buddy { - /* Maintain a free list for each order. */ - struct rb_root **free_trees; - +/* private: */ /* - * Maintain explicit binary tree(s) to track the allocation of the - * address space. This gives us a simple way of finding a buddy block - * and performing the potentially recursive merge step when freeing a - * block. Nodes are either allocated or free, in which case they will - * also exist on the respective free list. + * Array of red-black trees for free block management. + * Indexed as free_trees[clear/dirty][order] where: + * - Index 0 (DRM_BUDDY_DIRTY_TREE): blocks with unknown content + * - Index 1 (DRM_BUDDY_CLEAR_TREE): blocks with zeroed content + * Each tree holds free blocks of the corresponding order. */ - struct drm_buddy_block **roots; - + struct rb_root **free_trees; /* - * Anything from here is public, and remains static for the lifetime of - * the mm. Everything above is considered do-not-touch. + * Array of root blocks representing the top-level blocks of the + * binary tree(s). Multiple roots exist when the total size is not + * a power of two, with each root being the largest power-of-two + * that fits in the remaining space. */ + struct drm_buddy_block **roots; +/* public: */ unsigned int n_roots; unsigned int max_order; - - /* Must be at least SZ_4K */ u64 chunk_size; u64 size; u64 avail; -- 2.52.0
