|
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [PATCH] docs: Add/Improve function documentation for NUMA code
---
xen/arch/x86/srat.c | 45 ++++++++++++++++++++++++++++++++++++++--
xen/arch/x86/x86_64/mm.c | 22 ++++++++++++++++++--
xen/common/numa.c | 27 ++++++++++++++++++++++--
3 files changed, 88 insertions(+), 6 deletions(-)
diff --git a/xen/arch/x86/srat.c b/xen/arch/x86/srat.c
index 688f410287..a7f6b79324 100644
--- a/xen/arch/x86/srat.c
+++ b/xen/arch/x86/srat.c
@@ -51,6 +51,22 @@ nodeid_t pxm_to_node(unsigned pxm)
return NUMA_NO_NODE;
}
+/**
+ * @brief Set up a NUMA node based on the given proximity domain (pxm).
+ *
+ * If the proximity domain is already found in the pxm2node array, this
function
+ * returns the node ID associated with the given proximity domain.
+ *
+ * Otherwise, it assigns a new node ID to the proximity domain and returns it.
+ * If the maximum number of nodes has been reached, it returns an error code.
+ *
+ * @param pxm The proximity domain to set up or to find in the pxm2node array.
+ * @return The node ID associated with the given proximity domain,
+ * or NUMA_NO_NODE if the setup fails
+ * or the maximum number of nodes has been reached.
+ *
+ * @note Uses a static variable to assign the next NUMA node ID to be assigned.
+ */
nodeid_t setup_node(unsigned pxm)
{
nodeid_t node;
@@ -212,7 +228,19 @@ acpi_numa_processor_affinity_init(const struct
acpi_srat_cpu_affinity *pa)
pxm, pa->apic_id, node);
}
-/* Callback for parsing of the Proximity Domain <-> Memory Area mappings */
+/**
+ * @brief Initialize memory affinity for an SRAT memory affinity structure.
+ * @param ma Pointer to the ACPI SRAT memory affinity structure to be parsed.
+ *
+ * Callback for parsing of the Proximity Domain <-> Memory Area mappings
+ * provided by the ACPI SRAT(System Resource Affinity Table)
+ *
+ * This function is called during the initialization phase and is responsible
+ * for setting up memory affinity information for NUMA nodes
+ * based on the provided ACPI SRAT entries.
+ *
+ * If valid, it updates the memory block information for the specified node.
+ */
void __init
acpi_numa_memory_affinity_init(const struct acpi_srat_mem_affinity *ma)
{
@@ -314,16 +342,29 @@ void __init srat_parse_regions(paddr_t addr)
pfn_pdx_hole_setup(mask >> PAGE_SHIFT);
}
+/**
+ * @brief Find the proximity domain of a given NUMA node ID
+ *
+ * @param node The NUMA node ID to look up.
+ * @return The proximity domain of the given NUMA node ID, or 0 if not found
+ *
+ * This funciton uses the pxm2node array to find the proximity domain:
+ * The pxm2node array maps proximity domains to NUMA nodes and is indexed by
the
+ * proximity domain. Each entry contains the proximity domain and the NUMA
node.
+ */
unsigned int numa_node_to_arch_nid(nodeid_t n)
{
unsigned int i;
+ /* If the NUMA node is found using the index, return the pxm directly:
*/
if ((n < ARRAY_SIZE(pxm2node)) && (pxm2node[n].node == n))
return pxm2node[n].pxm;
+
+ /* Else, scan over the pxm2node array to find the architecture node ID:
*/
for (i = 0; i < ARRAY_SIZE(pxm2node); i++)
if (pxm2node[i].node == n)
return pxm2node[i].pxm;
- return 0;
+ return 0; /* If the node ID is not found, return 0. */
}
u8 __node_distance(nodeid_t a, nodeid_t b)
diff --git a/xen/arch/x86/x86_64/mm.c b/xen/arch/x86/x86_64/mm.c
index 0d8e602529..e8571000b2 100644
--- a/xen/arch/x86/x86_64/mm.c
+++ b/xen/arch/x86/x86_64/mm.c
@@ -1218,8 +1218,26 @@ static int mem_hotadd_check(unsigned long spfn, unsigned
long epfn)
}
/*
- * A bit paranoid for memory allocation failure issue since
- * it may be reason for memory add
+ * @brief Add a contiguous range of pages to the Xen hypervisor heap
+ *
+ * Update the machine-to-phys (m2p) and frame tables, the max_page, max_pdx and
+ * total_pages values, and set the page table entries for the new memory range.
+ *
+ * Also update the node_start_pfn and node_spanned_pages fields in the
node_data
+ * structure for the NUMA node that the memory range belongs to.
+ *
+ * If the NUMA node is offline, set the node's online flag.
+ *
+ * If the hardware domain uses an IOMMU and the IOMMU pagetable
+ * is not using the HW domain's P2M table or is not kept in sync,
+ * also update the IOMMU maps for the newly added memory.
+ *
+ * When memory allocations or adding the memory fails, revert any changes made.
+ *
+ * @param spfn The starting page frame number of the range.
+ * @param epfn The ending page frame number of the range.
+ * @param pxm The proximity domain of the range, which represents the NUMA
node.
+ * @return 0 on success, or a negative error code on failure.
*/
int memory_add(unsigned long spfn, unsigned long epfn, unsigned int pxm)
{
diff --git a/xen/common/numa.c b/xen/common/numa.c
index ce3991929c..5db0a6745e 100644
--- a/xen/common/numa.c
+++ b/xen/common/numa.c
@@ -140,6 +140,18 @@ bool __init numa_memblks_available(void)
}
/*
+ * @brief Update the memory blocks of a NUMA node.
+ *
+ * Check for overlaps and interleaves with existing memory blocks for the node.
+ * If none, update the node's memory range and maintain the sorting of blocks.
+ *
+ * @param node The node ID for which memory blocks are being updated.
+ * @param arch_nid The architecture node ID associated with the memory.
+ * @param start The starting physical address of the memory block.
+ * @param size The size of the memory block.
+ * @param hotplug Indicates if the memory is being hotplugged.
+ * @return true if the memory block was successfully added, false otherwise.
+ *
* This function will be called by NUMA memory affinity initialization to
* update NUMA node's memory range. In this function, we assume all memory
* regions belonging to a single node are in one chunk. Holes (or MMIO
@@ -264,8 +276,17 @@ bool __init numa_update_node_memblks(nodeid_t node,
unsigned int arch_nid,
}
/*
+ * @brief Check if all RAM ranges are covered by NUMA nodes.
+ *
* Sanity check to catch more bad SRATs (they are amazingly common).
* Make sure the PXMs cover all memory.
+ *
+ * This function iterates through the memory map and checks if each RAM range
+ * is covered by any of the NUMA nodes. If a RAM range is not covered by any
+ * node, it logs an error and returns false. If all RAM ranges are covered,
+ * it returns true.
+ *
+ * @return true if all RAM ranges are covered by NUMA nodes, false otherwise.
*/
static bool __init nodes_cover_memory(void)
{
@@ -291,18 +312,20 @@ static bool __init nodes_cover_memory(void)
do {
found = false;
+ /* Loop over the NUMA nodes and if check they cover this mapping */
for_each_node_mask ( j, memory_nodes_parsed )
+ /* Check if this node's spanned pages are inside this mapping
*/
if ( start < numa_nodes[j].end && end > numa_nodes[j].start )
{
if ( start >= numa_nodes[j].start )
{
- start = numa_nodes[j].end;
+ start = numa_nodes[j].end; /* Check following memory
*/
found = true;
}
if ( end <= numa_nodes[j].end )
{
- end = numa_nodes[j].start;
+ end = numa_nodes[j].start; /* check preceding memory
*/
found = true;
}
}
--
2.43.0
|
 |
Lists.xenproject.org is hosted with RackSpace, monitoring our |