x86-64, NUMA: Better explain numa_distance handling

Handling of out-of-bounds distances and allocation failure can use
better documentation.  Add it.

Signed-off-by: Tejun Heo <tj@kernel.org>
Cc: Yinghai Lu <yinghai@kernel.org>
Acked-by: David Rientjes <rientjes@google.com>

2 files changed, 15 insertions, 2 deletions

diff --git a/arch/x86/mm/numa_64.c b/arch/x86/mm/numa_64.c
index 541746fdeb4b..74064e8ae79f 100644
--- a/arch/x86/mm/numa_64.c
+++ b/arch/x86/mm/numa_64.c
@@ -392,11 +392,12 @@ void __init numa_reset_distance(void)
 {
         size_t size = numa_distance_cnt * numa_distance_cnt * sizeof(numa_distance[0]);
 
+        /* numa_distance could be 1LU marking allocation failure, test cnt */
         if (numa_distance_cnt)
                 memblock_x86_free_range(__pa(numa_distance),
                                         __pa(numa_distance) + size);
         numa_distance_cnt = 0;
-        numa_distance = NULL;
+        numa_distance = NULL;   /* enable table creation */
 }
 
 static int __init numa_alloc_distance(void)
@@ -447,6 +448,14 @@ static int __init numa_alloc_distance(void)
  * Set the distance from node @from to @to to @distance.  If distance table
  * doesn't exist, one which is large enough to accomodate all the currently
  * known nodes will be created.
+ *
+ * If such table cannot be allocated, a warning is printed and further
+ * calls are ignored until the distance table is reset with
+ * numa_reset_distance().
+ *
+ * If @from or @to is higher than the highest known node at the time of
+ * table creation or @distance doesn't make sense, the call is ignored.
+ * This is to allow simplification of specific NUMA config implementations.
  */
 void __init numa_set_distance(int from, int to, int distance)
 {
diff --git a/arch/x86/mm/numa_emulation.c b/arch/x86/mm/numa_emulation.c
index 0afa25d967ba..aeecea93820f 100644
--- a/arch/x86/mm/numa_emulation.c
+++ b/arch/x86/mm/numa_emulation.c
@@ -379,7 +379,11 @@ void __init numa_emulation(struct numa_meminfo *numa_meminfo, int numa_dist_cnt)
                 if (emu_nid_to_phys[i] == NUMA_NO_NODE)
                         emu_nid_to_phys[i] = 0;
 
-        /* transform distance table */
+        /*
+         * Transform distance table.  numa_set_distance() ignores all
+         * out-of-bound distances.  Just call it for every possible node
+         * combination.
+         */
         numa_reset_distance();
         for (i = 0; i < MAX_NUMNODES; i++) {
                 for (j = 0; j < MAX_NUMNODES; j++) {