Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit e18c0412 authored by Daniel Vetter's avatar Daniel Vetter
Browse files

drm/doc: Add function reference documentation for drm_mm.c 



While at it do a tiny bit of interface cleanup and convert boolean
return values to bool. With this patch all exported functions and inline
helpers which are part of the drm_mm public interface are documented.

Also drop superflous extern function modifiers since most of drm_mm.h
doesn't use them - more consistent that way.

Reviewed-by: default avatarAlex Deucher <alexander.deucher@amd.com>
Signed-off-by: default avatarDaniel Vetter <daniel.vetter@ffwll.ch>
parent 93110be6

Documentation/DocBook/drm.tmpl

+5 −0
Original line number Diff line number Diff line
@@ -931,6 +931,11 @@ struct drm_gem_object * (*gem_prime_import)(struct drm_device *dev, 
!Pdrivers/gpu/drm/drm_mm.c lru scan roaster

	</sect3>

      </sect2>

      <sect2>

	<title>DRM MM Range Allocator Function References</title>

!Edrivers/gpu/drm/drm_mm.c

!Iinclude/drm/drm_mm.h

      </sect2>

  </sect1>



  <!-- Internals: mode setting -->

drivers/gpu/drm/drm_mm.c

+121 −23
Original line number Diff line number Diff line
@@ -144,6 +144,20 @@ static void drm_mm_insert_helper(struct drm_mm_node *hole_node, 
	}

}



/**

 * drm_mm_reserve_node - insert an pre-initialized node

 * @mm: drm_mm allocator to insert @node into

 * @node: drm_mm_node to insert

 *

 * This functions inserts an already set-up drm_mm_node into the allocator,

 * meaning that start, size and color must be set by the caller. This is useful

 * to initialize the allocator with preallocated objects which must be set-up

 * before the range allocator can be set-up, e.g. when taking over a firmware

 * framebuffer.

 *

 * Returns:

 * 0 on success, -ENOSPC if there's no hole where @node is.

 */

int drm_mm_reserve_node(struct drm_mm *mm, struct drm_mm_node *node)

{

	struct drm_mm_node *hole;
@@ -185,9 +199,18 @@ int drm_mm_reserve_node(struct drm_mm *mm, struct drm_mm_node *node) 
EXPORT_SYMBOL(drm_mm_reserve_node);



/**

 * Search for free space and insert a preallocated memory node. Returns

 * -ENOSPC if no suitable free area is available. The preallocated memory node

 * must be cleared.

 * drm_mm_insert_node_generic - search for space and insert @node

 * @mm: drm_mm to allocate from

 * @node: preallocate node to insert

 * @size: size of the allocation

 * @alignment: alignment of the allocation

 * @color: opaque tag value to use for this node

 * @flags: flags to fine-tune the allocation

 *

 * The preallocated node must be cleared to 0.

 *

 * Returns:

 * 0 on success, -ENOSPC if there's no suitable hole.

 */

int drm_mm_insert_node_generic(struct drm_mm *mm, struct drm_mm_node *node,

			       unsigned long size, unsigned alignment,
@@ -259,9 +282,20 @@ static void drm_mm_insert_helper_range(struct drm_mm_node *hole_node, 
}



/**

 * Search for free space and insert a preallocated memory node. Returns

 * -ENOSPC if no suitable free area is available. This is for range

 * restricted allocations. The preallocated memory node must be cleared.

 * drm_mm_insert_node_in_range_generic - ranged search for space and insert @node

 * @mm: drm_mm to allocate from

 * @node: preallocate node to insert

 * @size: size of the allocation

 * @alignment: alignment of the allocation

 * @color: opaque tag value to use for this node

 * @start: start of the allowed range for this node

 * @end: end of the allowed range for this node

 * @flags: flags to fine-tune the allocation

 *

 * The preallocated node must be cleared to 0.

 *

 * Returns:

 * 0 on success, -ENOSPC if there's no suitable hole.

 */

int drm_mm_insert_node_in_range_generic(struct drm_mm *mm, struct drm_mm_node *node,

					unsigned long size, unsigned alignment, unsigned long color,
@@ -284,7 +318,12 @@ int drm_mm_insert_node_in_range_generic(struct drm_mm *mm, struct drm_mm_node *n 
EXPORT_SYMBOL(drm_mm_insert_node_in_range_generic);



/**

 * Remove a memory node from the allocator.

 * drm_mm_remove_node - Remove a memory node from the allocator.

 * @node: drm_mm_node to remove

 *

 * This just removes a node from its drm_mm allocator. The node does not need to

 * be cleared again before it can be re-inserted into this or any other drm_mm

 * allocator. It is a bug to call this function on a un-allocated node.

 */

void drm_mm_remove_node(struct drm_mm_node *node)

{
@@ -421,7 +460,13 @@ static struct drm_mm_node *drm_mm_search_free_in_range_generic(const struct drm_ 
}



/**

 * Moves an allocation. To be used with embedded struct drm_mm_node.

 * drm_mm_replace_node - move an allocation from @old to @new

 * @old: drm_mm_node to remove from the allocator

 * @new: drm_mm_node which should inherit @old's allocation

 *

 * This is useful for when drivers embed the drm_mm_node structure and hence

 * can't move allocations by reassigning pointers. It's a combination of remove

 * and insert with the guarantee that the allocation start will match.

 */

void drm_mm_replace_node(struct drm_mm_node *old, struct drm_mm_node *new)

{
@@ -467,12 +512,18 @@ EXPORT_SYMBOL(drm_mm_replace_node); 
 */



/**

 * Initializa lru scanning.

 * drm_mm_init_scan - initialize lru scanning

 * @mm: drm_mm to scan

 * @size: size of the allocation

 * @alignment: alignment of the allocation

 * @color: opaque tag value to use for the allocation

 *

 * This simply sets up the scanning routines with the parameters for the desired

 * hole.

 * hole. Note that there's no need to specify allocation flags, since they only

 * change the place a node is allocated from within a suitable hole.

 *

 * Warning: As long as the scan list is non-empty, no other operations than

 * Warning:

 * As long as the scan list is non-empty, no other operations than

 * adding/removing nodes to/from the scan list are allowed.

 */

void drm_mm_init_scan(struct drm_mm *mm,
@@ -492,12 +543,20 @@ void drm_mm_init_scan(struct drm_mm *mm, 
EXPORT_SYMBOL(drm_mm_init_scan);



/**

 * Initializa lru scanning.

 * drm_mm_init_scan - initialize range-restricted lru scanning

 * @mm: drm_mm to scan

 * @size: size of the allocation

 * @alignment: alignment of the allocation

 * @color: opaque tag value to use for the allocation

 * @start: start of the allowed range for the allocation

 * @end: end of the allowed range for the allocation

 *

 * This simply sets up the scanning routines with the parameters for the desired

 * hole. This version is for range-restricted scans.

 * hole. Note that there's no need to specify allocation flags, since they only

 * change the place a node is allocated from within a suitable hole.

 *

 * Warning: As long as the scan list is non-empty, no other operations than

 * Warning:

 * As long as the scan list is non-empty, no other operations than

 * adding/removing nodes to/from the scan list are allowed.

 */

void drm_mm_init_scan_with_range(struct drm_mm *mm,
@@ -521,12 +580,16 @@ void drm_mm_init_scan_with_range(struct drm_mm *mm, 
EXPORT_SYMBOL(drm_mm_init_scan_with_range);



/**

 * drm_mm_scan_add_block - add a node to the scan list

 * @node: drm_mm_node to add

 *

 * Add a node to the scan list that might be freed to make space for the desired

 * hole.

 *

 * Returns non-zero, if a hole has been found, zero otherwise.

 * Returns:

 * True if a hole has been found, false otherwise.

 */

int drm_mm_scan_add_block(struct drm_mm_node *node)

bool drm_mm_scan_add_block(struct drm_mm_node *node)

{

	struct drm_mm *mm = node->mm;

	struct drm_mm_node *prev_node;
@@ -566,15 +629,16 @@ int drm_mm_scan_add_block(struct drm_mm_node *node) 
			    mm->scan_size, mm->scan_alignment)) {

		mm->scan_hit_start = hole_start;

		mm->scan_hit_end = hole_end;

		return 1;

		return true;

	}



	return 0;

	return false;

}

EXPORT_SYMBOL(drm_mm_scan_add_block);



/**

 * Remove a node from the scan list.

 * drm_mm_scan_remove_block - remove a node from the scan list

 * @node: drm_mm_node to remove

 *

 * Nodes _must_ be removed in the exact same order from the scan list as they

 * have been added, otherwise the internal state of the memory manager will be
@@ -584,10 +648,11 @@ EXPORT_SYMBOL(drm_mm_scan_add_block); 
 * immediately following drm_mm_search_free with !DRM_MM_SEARCH_BEST will then

 * return the just freed block (because its at the top of the free_stack list).

 *

 * Returns one if this block should be evicted, zero otherwise. Will always

 * return zero when no hole has been found.

 * Returns:

 * True if this block should be evicted, false otherwise. Will always

 * return false when no hole has been found.

 */

int drm_mm_scan_remove_block(struct drm_mm_node *node)

bool drm_mm_scan_remove_block(struct drm_mm_node *node)

{

	struct drm_mm *mm = node->mm;

	struct drm_mm_node *prev_node;
@@ -608,7 +673,15 @@ int drm_mm_scan_remove_block(struct drm_mm_node *node) 
}

EXPORT_SYMBOL(drm_mm_scan_remove_block);



int drm_mm_clean(struct drm_mm * mm)

/**

 * drm_mm_clean - checks whether an allocator is clean

 * @mm: drm_mm allocator to check

 *

 * Returns:

 * True if the allocator is completely free, false if there's still a node

 * allocated in it.

 */

bool drm_mm_clean(struct drm_mm * mm)

{

	struct list_head *head = &mm->head_node.node_list;
@@ -616,6 +689,14 @@ int drm_mm_clean(struct drm_mm * mm) 
}

EXPORT_SYMBOL(drm_mm_clean);



/**

 * drm_mm_init - initialize a drm-mm allocator

 * @mm: the drm_mm structure to initialize

 * @start: start of the range managed by @mm

 * @size: end of the range managed by @mm

 *

 * Note that @mm must be cleared to 0 before calling this function.

 */

void drm_mm_init(struct drm_mm * mm, unsigned long start, unsigned long size)

{

	INIT_LIST_HEAD(&mm->hole_stack);
@@ -637,6 +718,13 @@ void drm_mm_init(struct drm_mm * mm, unsigned long start, unsigned long size) 
}

EXPORT_SYMBOL(drm_mm_init);



/**

 * drm_mm_takedown - clean up a drm_mm allocator

 * @mm: drm_mm allocator to clean up

 *

 * Note that it is a bug to call this function on an allocator which is not

 * clean.

 */

void drm_mm_takedown(struct drm_mm * mm)

{

	WARN(!list_empty(&mm->head_node.node_list),
@@ -662,6 +750,11 @@ static unsigned long drm_mm_debug_hole(struct drm_mm_node *entry, 
	return 0;

}



/**

 * drm_mm_debug_table - dump allocator state to dmesg

 * @mm: drm_mm allocator to dump

 * @prefix: prefix to use for dumping to dmesg

 */

void drm_mm_debug_table(struct drm_mm *mm, const char *prefix)

{

	struct drm_mm_node *entry;
@@ -700,6 +793,11 @@ static unsigned long drm_mm_dump_hole(struct seq_file *m, struct drm_mm_node *en 
	return 0;

}



/**

 * drm_mm_dump_table - dump allocator state to a seq_file

 * @m: seq_file to dump to

 * @mm: drm_mm allocator to dump

 */

int drm_mm_dump_table(struct seq_file *m, struct drm_mm *mm)

{

	struct drm_mm_node *entry;

include/drm/drm_mm.h

+125 −29
Original line number Diff line number Diff line
@@ -85,11 +85,31 @@ struct drm_mm { 
			     unsigned long *start, unsigned long *end);

};



/**

 * drm_mm_node_allocated - checks whether a node is allocated

 * @node: drm_mm_node to check

 *

 * Drivers should use this helpers for proper encapusulation of drm_mm

 * internals.

 *

 * Returns:

 * True if the @node is allocated.

 */

static inline bool drm_mm_node_allocated(struct drm_mm_node *node)

{

	return node->allocated;

}



/**

 * drm_mm_initialized - checks whether an allocator is initialized

 * @mm: drm_mm to check

 *

 * Drivers should use this helpers for proper encapusulation of drm_mm

 * internals.

 *

 * Returns:

 * True if the @mm is initialized.

 */

static inline bool drm_mm_initialized(struct drm_mm *mm)

{

	return mm->hole_stack.next;
@@ -100,6 +120,17 @@ static inline unsigned long __drm_mm_hole_node_start(struct drm_mm_node *hole_no 
	return hole_node->start + hole_node->size;

}



/**

 * drm_mm_hole_node_start - computes the start of the hole following @node

 * @hole_node: drm_mm_node which implicitly tracks the following hole

 *

 * This is useful for driver-sepific debug dumpers. Otherwise drivers should not

 * inspect holes themselves. Drivers must check first whether a hole indeed

 * follows by looking at node->hole_follows.

 *

 * Returns:

 * Start of the subsequent hole.

 */

static inline unsigned long drm_mm_hole_node_start(struct drm_mm_node *hole_node)

{

	BUG_ON(!hole_node->hole_follows);
@@ -112,18 +143,49 @@ static inline unsigned long __drm_mm_hole_node_end(struct drm_mm_node *hole_node 
			  struct drm_mm_node, node_list)->start;

}



/**

 * drm_mm_hole_node_end - computes the end of the hole following @node

 * @hole_node: drm_mm_node which implicitly tracks the following hole

 *

 * This is useful for driver-sepific debug dumpers. Otherwise drivers should not

 * inspect holes themselves. Drivers must check first whether a hole indeed

 * follows by looking at node->hole_follows.

 *

 * Returns:

 * End of the subsequent hole.

 */

static inline unsigned long drm_mm_hole_node_end(struct drm_mm_node *hole_node)

{

	return __drm_mm_hole_node_end(hole_node);

}



/**

 * drm_mm_for_each_node - iterator to walk over all allocated nodes

 * @entry: drm_mm_node structure to assign to in each iteration step

 * @mm: drm_mm allocator to walk

 *

 * This iterator walks over all nodes in the range allocator. It is implemented

 * with list_for_each, so not save against removal of elements.

 */

#define drm_mm_for_each_node(entry, mm) list_for_each_entry(entry, \

						&(mm)->head_node.node_list, \

						node_list)



/* Note that we need to unroll list_for_each_entry in order to inline

 * setting hole_start and hole_end on each iteration and keep the

 * macro sane.

/**

 * drm_mm_for_each_hole - iterator to walk over all holes

 * @entry: drm_mm_node used internally to track progress

 * @mm: drm_mm allocator to walk

 * @hole_start: ulong variable to assign the hole start to on each iteration

 * @hole_end: ulong variable to assign the hole end to on each iteration

 *

 * This iterator walks over all holes in the range allocator. It is implemented

 * with list_for_each, so not save against removal of elements. @entry is used

 * internally and will not reflect a real drm_mm_node for the very first hole.

 * Hence users of this iterator may not access it.

 *

 * Implementation Note:

 * We need to inline list_for_each_entry in order to be able to set hole_start

 * and hole_end on each iteration while keeping the macro sane.

 */

#define drm_mm_for_each_hole(entry, mm, hole_start, hole_end) \

	for (entry = list_entry((mm)->hole_stack.next, struct drm_mm_node, hole_stack); \
@@ -136,14 +198,30 @@ static inline unsigned long drm_mm_hole_node_end(struct drm_mm_node *hole_node) 
/*

 * Basic range manager support (drm_mm.c)

 */

extern int drm_mm_reserve_node(struct drm_mm *mm, struct drm_mm_node *node);

int drm_mm_reserve_node(struct drm_mm *mm, struct drm_mm_node *node);



extern int drm_mm_insert_node_generic(struct drm_mm *mm,

int drm_mm_insert_node_generic(struct drm_mm *mm,

			       struct drm_mm_node *node,

			       unsigned long size,

			       unsigned alignment,

			       unsigned long color,

			       enum drm_mm_search_flags flags);

/**

 * drm_mm_insert_node - search for space and insert @node

 * @mm: drm_mm to allocate from

 * @node: preallocate node to insert

 * @size: size of the allocation

 * @alignment: alignment of the allocation

 * @flags: flags to fine-tune the allocation

 *

 * This is a simplified version of drm_mm_insert_node_generic() with @color set

 * to 0.

 *

 * The preallocated node must be cleared to 0.

 *

 * Returns:

 * 0 on success, -ENOSPC if there's no suitable hole.

 */

static inline int drm_mm_insert_node(struct drm_mm *mm,

				     struct drm_mm_node *node,

				     unsigned long size,
@@ -153,7 +231,7 @@ static inline int drm_mm_insert_node(struct drm_mm *mm, 
	return drm_mm_insert_node_generic(mm, node, size, alignment, 0, flags);

}



extern int drm_mm_insert_node_in_range_generic(struct drm_mm *mm,

int drm_mm_insert_node_in_range_generic(struct drm_mm *mm,

					struct drm_mm_node *node,

					unsigned long size,

					unsigned alignment,
@@ -161,6 +239,24 @@ extern int drm_mm_insert_node_in_range_generic(struct drm_mm *mm, 
					unsigned long start,

					unsigned long end,

					enum drm_mm_search_flags flags);

/**

 * drm_mm_insert_node_in_range - ranged search for space and insert @node

 * @mm: drm_mm to allocate from

 * @node: preallocate node to insert

 * @size: size of the allocation

 * @alignment: alignment of the allocation

 * @start: start of the allowed range for this node

 * @end: end of the allowed range for this node

 * @flags: flags to fine-tune the allocation

 *

 * This is a simplified version of drm_mm_insert_node_in_range_generic() with

 * @color set to 0.

 *

 * The preallocated node must be cleared to 0.

 *

 * Returns:

 * 0 on success, -ENOSPC if there's no suitable hole.

 */

static inline int drm_mm_insert_node_in_range(struct drm_mm *mm,

					      struct drm_mm_node *node,

					      unsigned long size,
@@ -173,13 +269,13 @@ static inline int drm_mm_insert_node_in_range(struct drm_mm *mm, 
						   0, start, end, flags);

}



extern void drm_mm_remove_node(struct drm_mm_node *node);

extern void drm_mm_replace_node(struct drm_mm_node *old, struct drm_mm_node *new);

extern void drm_mm_init(struct drm_mm *mm,

void drm_mm_remove_node(struct drm_mm_node *node);

void drm_mm_replace_node(struct drm_mm_node *old, struct drm_mm_node *new);

void drm_mm_init(struct drm_mm *mm,

		 unsigned long start,

		 unsigned long size);

extern void drm_mm_takedown(struct drm_mm *mm);

extern int drm_mm_clean(struct drm_mm *mm);

void drm_mm_takedown(struct drm_mm *mm);

bool drm_mm_clean(struct drm_mm *mm);



void drm_mm_init_scan(struct drm_mm *mm,

		      unsigned long size,
@@ -191,10 +287,10 @@ void drm_mm_init_scan_with_range(struct drm_mm *mm, 
				 unsigned long color,

				 unsigned long start,

				 unsigned long end);

int drm_mm_scan_add_block(struct drm_mm_node *node);

int drm_mm_scan_remove_block(struct drm_mm_node *node);

bool drm_mm_scan_add_block(struct drm_mm_node *node);

bool drm_mm_scan_remove_block(struct drm_mm_node *node);



extern void drm_mm_debug_table(struct drm_mm *mm, const char *prefix);

void drm_mm_debug_table(struct drm_mm *mm, const char *prefix);

#ifdef CONFIG_DEBUG_FS

int drm_mm_dump_table(struct seq_file *m, struct drm_mm *mm);

#endif