linux-kernel - [PATCH v3 3/8] resource: Document find_resource_space() and resource

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-Id: <20240507102523.57320-4-ilpo.jarvinen@linux.intel.com>
Date: Tue,  7 May 2024 13:25:18 +0300
From: Ilpo Järvinen <ilpo.jarvinen@...ux.intel.com>
To: linux-pci@...r.kernel.org,
	Bjorn Helgaas <bhelgaas@...gle.com>,
	Lorenzo Pieralisi <lorenzo.pieralisi@....com>,
	Rob Herring <robh@...nel.org>,
	Krzysztof Wilczyński <kw@...ux.com>,
	Igor Mammedov <imammedo@...hat.com>,
	Mika Westerberg <mika.westerberg@...ux.intel.com>,
	Andy Shevchenko <andriy.shevchenko@...el.com>,
	"Rafael J . Wysocki" <rafael@...nel.org>,
	Jonathan Cameron <Jonathan.Cameron@...wei.com>,
	linux-kernel@...r.kernel.org
Cc: Ilpo Järvinen <ilpo.jarvinen@...ux.intel.com>,
	Lidong Wang <lidong.wang@...el.com>,
	Andy Shevchenko <andriy.shevchenko@...ux.intel.com>
Subject: [PATCH v3 3/8] resource: Document find_resource_space() and resource_constraint

Document find_resource_space() and the struct resource_constraint as
they are going to be exposed outside of resource.c.

Tested-by: Lidong Wang <lidong.wang@...el.com>
Signed-off-by: Ilpo Järvinen <ilpo.jarvinen@...ux.intel.com>
Reviewed-by: Andy Shevchenko <andriy.shevchenko@...ux.intel.com>
Reviewed-by: Mika Westerberg <mika.westerberg@...ux.intel.com>
---
 kernel/resource.c | 29 ++++++++++++++++++++++++++---
 1 file changed, 26 insertions(+), 3 deletions(-)

diff --git a/kernel/resource.c b/kernel/resource.c
index e163e0a8f2f8..3f15a32d9c42 100644
--- a/kernel/resource.c
+++ b/kernel/resource.c
@@ -48,7 +48,19 @@ struct resource iomem_resource = {
 };
 EXPORT_SYMBOL(iomem_resource);
 
-/* constraints to be met while allocating resources */
+/**
+ * struct resource_constraint - constraints to be met while searching empty
+ *				resource space
+ * @min:		The minimum address for the memory range
+ * @max:		The maximum address for the memory range
+ * @align:		Alignment for the start address of the empty space
+ * @alignf:		Additional alignment constraints callback
+ * @alignf_data:	Data provided for @alignf callback
+ *
+ * Contains the range and alignment constraints that have to be met during
+ * find_resource_space(). @alignf can be NULL indicating no alignment beyond
+ * @align is necessary.
+ */
 struct resource_constraint {
 	resource_size_t min, max, align;
 	resource_size_t (*alignf)(void *, const struct resource *,
@@ -686,8 +698,19 @@ next:		if (!this || this->end == root->end)
 	return -EBUSY;
 }
 
-/*
- * Find empty space in the resource tree given range and alignment.
+/**
+ * find_resource_space - Find empty space in the resource tree
+ * @root:	Root resource descriptor
+ * @new:	Resource descriptor awaiting an empty resource space
+ * @size:	The minimum size of the empty space
+ * @constraint:	The range and alignment constraints to be met
+ *
+ * Finds an empty space under @root in the resource tree satisfying range and
+ * alignment @constraints.
+ *
+ * Return:
+ * * %0		- if successful, @new members start, end, and flags are altered.
+ * * %-EBUSY	- if no empty space was found.
  */
 static int find_resource_space(struct resource *root, struct resource *new,
 			       resource_size_t size,
-- 
2.39.2