Use APIC IDs instead of logical CPU numbers

Validate CPU specifications against physical APIC IDs read from
/sys/devices/system/cpu/*/topology/apic_id rather than logical CPU
count. This allows specifying CPUs on multi-socket systems where
APIC IDs are non-contiguous (e.g., socket 1 uses APIC IDs 128+).

Signed-off-by: Cong Wang <cwang@multikernel.io>

Author: congwang-mk

src/kerf/create/main.py

@@ -137,7 +137,7 @@ def _allocate_spread(
                 numa_cpu_lists[numa_node_id] = sorted(numa_cpus)
 
         if not numa_cpu_lists:
-            raise ResourceError(f"No available CPUs in specified NUMA nodes: {numa_nodes}")
+            raise ResourceError(f"No available APIC IDs in specified NUMA nodes: {numa_nodes}")
 
         allocated = []
         numa_indices = {node_id: 0 for node_id in numa_cpu_lists}
@@ -187,7 +187,7 @@ def _allocate_local(
         if len(numa_cpus) >= count:
             return sorted(numa_cpus[:count])
         raise ResourceError(
-            f"Not enough CPUs in NUMA node {numa_node_id}: "
+            f"Not enough APIC IDs in NUMA node {numa_node_id}: "
             f"requested {count}, but only {len(numa_cpus)} available"
         )
 
@@ -200,7 +200,7 @@ def _allocate_local(
         if len(numa_cpus) >= count:
             return sorted(numa_cpus[:count])
 
-    raise ResourceError(f"No single NUMA node has {count} available CPUs for 'local' affinity")
+    raise ResourceError(f"No single NUMA node has {count} available APIC IDs for 'local' affinity")
 
 
 def allocate_cpus_from_pool(
@@ -236,11 +236,11 @@ def allocate_cpus_from_pool(
     if len(available) < count:
         if numa_nodes:
             raise ResourceError(
-                f"Not enough CPUs available in NUMA nodes {numa_nodes}: "
+                f"Not enough APIC IDs available in NUMA nodes {numa_nodes}: "
                 f"requested {count}, but only {len(available)} available"
             )
         raise ResourceError(
-            f"Not enough CPUs available: requested {count}, "
+            f"Not enough APIC IDs available: requested {count}, "
             f"but only {len(available)} available in pool"
         )
 
@@ -399,8 +399,9 @@ def dump_overlay_for_debug(
 @click.option(
     "--cpus",
     "-c",
-    help='Explicit CPU allocation: CPU IDs (e.g., "4" for CPU 4, "4-7" for range, '
-    '"4,5,6,7" for list, "4-7,10-12" for mixed). Mutually exclusive with --cpu-count',
+    help='Explicit APIC ID allocation (e.g., "128" for APIC ID 128, "128-134" for range, '
+    '"128,130,132" for list). Use physical APIC IDs, not logical CPU numbers. '
+    'Mutually exclusive with --cpu-count',
 )
 @click.option(
     "--cpu-count",
@@ -472,20 +473,20 @@ def create(  # pylint: disable=too-many-arguments,too-many-positional-arguments
 
     Examples:
 
-        # Create instance with CPUs 4-7 and 2GB memory (auto-assigned base)
-        kerf create web-server --cpus=4-7 --memory=2GB
+        # Create instance with APIC IDs 128-134 and 2GB memory (auto-assigned base)
+        kerf create web-server --cpus=128-134 --memory=2GB
 
         # Create instance with name after options
-        kerf create --cpus=8-15 --memory=8GB web-server
+        kerf create --cpus=128,130,132 --memory=8GB web-server
 
         # Create instance with specific memory base address
-        kerf create database --cpus=8-15 --memory=8GB --memory-base=0x100000000
+        kerf create database --cpus=128-142 --memory=8GB --memory-base=0x100000000
 
         # Create instance with devices
-        kerf create compute --cpus=16-23 --memory=4GB --devices=enp9s0_dev
+        kerf create compute --cpus=128-142 --memory=4GB --devices=enp9s0_dev
 
-        # Create instance with explicit single CPU
-        kerf create web-server --cpus=4 --memory=2GB
+        # Create instance with explicit single APIC ID
+        kerf create web-server --cpus=128 --memory=2GB
 
         # Create instance with auto-allocated CPU count
         kerf create web-server --cpu-count=4 --memory=2GB
@@ -539,7 +540,7 @@ def create(  # pylint: disable=too-many-arguments,too-many-positional-arguments
             try:
                 cpu_spec_value = parse_cpu_spec(cpus)
             except ValueError as e:
-                click.echo(f"Error: Invalid CPU specification '{cpus}': {e}", err=True)
+                click.echo(f"Error: Invalid APIC ID specification '{cpus}': {e}", err=True)
                 sys.exit(2)
 
         # Parse memory specification

src/kerf/init/main.py

@@ -346,6 +346,37 @@ def get_total_cpus_from_system() -> Optional[int]:
     return None
 
 
+def get_valid_apic_ids_from_system() -> Optional[set]:
+    """
+    Get set of valid APIC IDs from the system via sysfs.
+    Reads /sys/devices/system/cpu/cpuN/topology/apic_id for each CPU.
+    Returns set of valid APIC IDs or None if not available.
+    """
+    try:
+        cpu_dir = Path('/sys/devices/system/cpu')
+        if not cpu_dir.exists():
+            return None
+
+        apic_ids = set()
+        cpu_files = [f for f in cpu_dir.iterdir() if f.name.startswith('cpu') and f.name[3:].isdigit()]
+
+        for cpu_path in cpu_files:
+            apic_id_file = cpu_path / 'topology' / 'apic_id'
+            if apic_id_file.exists():
+                try:
+                    with open(apic_id_file, 'r', encoding='utf-8') as f:
+                        apic_id = int(f.read().strip())
+                        apic_ids.add(apic_id)
+                except (ValueError, IOError):
+                    pass
+
+        return apic_ids if apic_ids else None
+    except (OSError, ValueError):
+        pass
+
+    return None
+
+
 def build_baseline_from_cmdline(
     cpus: str,
     devices: Optional[str] = None,
@@ -371,27 +402,30 @@ def build_baseline_from_cmdline(
     except ValueError as e:
         raise ValueError(f"Invalid CPU specification '{cpus}': {e}") from e
 
-    system_total_cpus = get_total_cpus_from_system()
-    if system_total_cpus is None:
-        max_cpu = max(cpu_list) if cpu_list else 0
-        total_cpus = max_cpu + 1
-        if verbose:
-            click.echo(f"Warning: Could not determine total CPUs from system, using max from specification: {total_cpus}", err=True)
-    else:
-        total_cpus = system_total_cpus
-        max_specified = max(cpu_list) if cpu_list else -1
-        if max_specified >= total_cpus:
-            raise ValueError(
-                f"CPU {max_specified} specified but system only has {total_cpus} CPUs (0-{total_cpus-1})"
-            )
+    # Validate against valid APIC IDs on the system
+    valid_apic_ids = get_valid_apic_ids_from_system()
+    if valid_apic_ids is None:
+        raise KernelInterfaceError(
+            "Could not read APIC IDs from /sys/devices/system/cpu/*/topology/apic_id. "
+            "Ensure the system exposes CPU topology information."
+        )
+
+    invalid_cpus = set(cpu_list) - valid_apic_ids
+    if invalid_cpus:
+        raise ValueError(
+            f"Invalid APIC ID(s) specified: {sorted(invalid_cpus)}. "
+            f"Valid APIC IDs on this system: {sorted(valid_apic_ids)}"
+        )
 
+    # Total CPUs is based on the max APIC ID + 1 for sizing purposes
+    total_cpus = max(valid_apic_ids) + 1
+    # Host reserved are all valid APIC IDs not in the available list
     available_cpus = set(cpu_list)
-    all_cpus = set(range(total_cpus))
-    host_reserved_cpus = sorted(list(all_cpus - available_cpus))
+    host_reserved_cpus = sorted(list(valid_apic_ids - available_cpus))
 
     if 0 in available_cpus and len(host_reserved_cpus) == 0:
         if verbose:
-            click.echo("Warning: CPU 0 is in available list but no host-reserved CPUs. Moving CPU 0 to host-reserved.", err=True)
+            click.echo("Warning: APIC ID 0 is in available list but no host-reserved CPUs. Moving APIC ID 0 to host-reserved.", err=True)
         available_cpus.discard(0)
         host_reserved_cpus = [0]
         cpu_list = sorted(list(available_cpus))
@@ -407,10 +441,10 @@ def build_baseline_from_cmdline(
     total_bytes = memory_pool_base + memory_pool_bytes
     host_reserved_bytes = memory_pool_base
     if verbose:
-        click.echo(f"Parsed CPU specification: {cpus}")
-        click.echo(f"  Total CPUs: {total_cpus}")
-        click.echo(f"  Host-reserved CPUs: {host_reserved_cpus}")
-        click.echo(f"  Available CPUs: {cpu_list}")
+        click.echo(f"Parsed APIC ID specification: {cpus}")
+        click.echo(f"  Valid APIC IDs on system: {sorted(valid_apic_ids)}")
+        click.echo(f"  Host-reserved APIC IDs: {host_reserved_cpus}")
+        click.echo(f"  Available APIC IDs: {cpu_list}")
         click.echo("Memory pool from /proc/iomem:")
         click.echo(f"  Base: {hex(memory_pool_base)}")
         click.echo(f"  Size: {memory_pool_bytes} bytes ({memory_pool_bytes / (1024**3):.2f} GB)")
@@ -473,7 +507,7 @@ def build_baseline_from_cmdline(
 @click.command()
 @click.pass_context
 @click.option('--input', '-i', help='Input DTS or DTB file containing all resources. Mutually exclusive with --cpus and --devices. When used, all resources must come from the file.')
-@click.option('--cpus', '-c', help='CPU specification for baseline (e.g., "4-7" or "4,5,6,7"). Mutually exclusive with --input. Memory will be parsed from /proc/iomem.')
+@click.option('--cpus', '-c', help='APIC ID specification for baseline (e.g., "128-134" or "128,130,132"). Use physical APIC IDs, not logical CPU numbers. Mutually exclusive with --input. Memory will be parsed from /proc/iomem.')
 @click.option('--devices', '-d', help='Device names (comma-separated, e.g., "enp9s0_dev,nvme0"). Mutually exclusive with --input. Creates minimal device entries in baseline.')
 @click.option('--dry-run', is_flag=True, help='Validate without applying')
 @click.option('--report', is_flag=True, help='Generate detailed validation report')
@@ -501,11 +535,11 @@ def init(ctx: click.Context, input: Optional[str], cpus: Optional[str], devices:
         # Initialize from DTS file (all resources from file)
         kerf init --input=hardware.dts
 
-        # Initialize from command line (CPUs 4-7, memory from /proc/iomem)
-        kerf init --cpus=4-7
+        # Initialize from command line (APIC IDs 128-134, memory from /proc/iomem)
+        kerf init --cpus=128-134
 
-        # Initialize with CPUs and devices
-        kerf init --cpus=4-7 --devices=enp9s0_dev,nvme0
+        # Initialize with APIC IDs and devices
+        kerf init --cpus=128,130,132 --devices=enp9s0_dev,nvme0
 
         # Validate baseline without applying
         kerf init --input=hardware.dts --dry-run

src/kerf/resources.py

@@ -201,29 +201,29 @@ def validate_cpu_allocation(
 
     requested_set = set(requested_cpus)
 
-    # Check all requested CPUs exist in hardware
+    # Check all requested APIC IDs exist in hardware
     hardware_cpus = set(tree.hardware.cpus.available)
     invalid_cpus = requested_set - hardware_cpus
     if invalid_cpus:
         raise ResourceError(
-            f"Invalid CPUs requested: {sorted(invalid_cpus)}. "
-            f"Available CPUs: {sorted(hardware_cpus)}"
+            f"Invalid APIC IDs requested: {sorted(invalid_cpus)}. "
+            f"Available APIC IDs: {sorted(hardware_cpus)}"
         )
 
-    # Check CPUs are available
+    # Check APIC IDs are available
     unavailable = requested_set - available_cpus
     if unavailable:
-        # Find which instances are using these CPUs
+        # Find which instances are using these APIC IDs
         conflicts = []
         for instance in tree.instances.values():
             if instance.name == exclude_instance:
                 continue
             conflict_cpus = set(instance.resources.cpus) & unavailable
             if conflict_cpus:
-                conflicts.append(f"{instance.name} uses CPUs {sorted(conflict_cpus)}")
+                conflicts.append(f"{instance.name} uses APIC IDs {sorted(conflict_cpus)}")
 
         conflict_msg = ", ".join(conflicts) if conflicts else "allocated to other instances"
-        raise ResourceError(f"CPUs {sorted(unavailable)} are not available ({conflict_msg})")
+        raise ResourceError(f"APIC IDs {sorted(unavailable)} are not available ({conflict_msg})")
 
 
 def validate_memory_allocation(