### Analyze Local System Example

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/api-reference/main-entry-point.md

Example command to analyze the local system's CPU topology.

```bash
./cpu_topology64.out C 1
./cpu_topology64.out C 6
./cpu_topology64.out C 5
```

--------------------------------

### Get Number of Processors Example

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/api-reference/os-specific.md

An example demonstrating how to call `Os_GetNumberOfProcessors` and print the system's processor count. This illustrates a common use case for system information retrieval.

```c
unsigned int num_procs = Os_GetNumberOfProcessors();
printf("System has %u processors\n", num_procs);
```

--------------------------------

### Display Multi-Domain Topology Example

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/MANIFEST.txt

Provides an example of how to display processor topology with multiple levels or domains.

```c
void Display_ManyDomainExample(const GLOBAL_DATA* data) {
    // Implementation for displaying complex, multi-domain topologies.
}
```

--------------------------------

### Compare Multiple Systems Example

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/api-reference/main-entry-point.md

Shows how to save CPU topology data from one system and load it on another to compare APIC ID layouts.

```bash
./cpu_topology64.out S system_1.cpuid
```

```bash
./cpu_topology64.out L system_1.cpuid 4
```

--------------------------------

### Save and Analyze Later Example

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/api-reference/main-entry-point.md

Demonstrates saving CPU topology data to a file on one system and loading it on another for later analysis.

```bash
./cpu_topology64.out S intel_system.cpuid
```

```bash
./cpu_topology64.out L intel_system.cpuid 1
./cpu_topology64.out L intel_system.cpuid 6
```

--------------------------------

### CPUID File Format Example

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/api-reference/file-io.md

This example demonstrates the structure of a CPUID data file, showing leaf, subleaf, and APIC ID entries.

```text
L 1
S 0 1234 5678 9ABC DEF0
L 4
S 0 12345678 90ABCDEF 11223344 55667788
L 4
S 0 FEDCBA98 76543210 AABBCCDD 44332211
A 0
A 4
A 12
```

--------------------------------

### Read CPUID Registers Example

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/api-reference/os-specific.md

An example demonstrating how to call `Os_Platform_Read_Cpuid` and print the APIC ID. This shows a typical usage pattern for retrieving specific CPU information.

```c
CPUID_REGISTERS cpuid;
Os_Platform_Read_Cpuid(0x1F, 0, &cpuid);
printf("APIC ID: 0x%x\n", cpuid.x.Register.Edx);
```

--------------------------------

### Real-world CPUID File Content Example

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/api-reference/file-io.md

This example shows a more complex CPUID file content, representing a system with multiple processors and detailed cache information across different leaves.

```text
L 0
S 0 22 1732050 1666057 49513569
L 1
S 0 655412 33554688 4043379207 3735150591
L 4
S 0 1010100 1023 63 0
S 1 2020100 1535 255 0
S 2 2040100 4095 4095 0
S 3 7120100 8191 20479 0
L 4
S 0 1010100 1023 63 0
S 1 2020100 1535 255 0
S 2 2040100 4095 4095 0
S 3 7120100 8191 20479 0
L 11
S 0 1 2 256 0
S 1 5 28 513 0
S 2 0 0 2 0
L 31
S 0 1 2 256 0
S 1 5 28 513 1
S 2 0 0 2 0
A 0
A 1
A 2
A 3
```

--------------------------------

### Programmatic Usage Example in C

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/README.md

Illustrates how to use the Processor Topology Enumeration library programmatically in C. It shows initialization, reading CPUID, getting processor count, setting thread affinity, and parsing topology information.

```c
#include "cpuid_topology.h"

int main() {
    // Initialize
    CpuidTopology_InitGlobal();
    
    // Read CPUID
    CPUID_REGISTERS cpuid;
    Tools_ReadCpuid(0x1F, 0, &cpuid);
    
    // Get processor count
    unsigned int num_procs = Tools_GetNumberOfProcessors();
    
    // Iterate processors
    for (unsigned int i = 0; i < num_procs; i++) {
        Tools_SetAffinity(i);
        Tools_ReadCpuid(0x1F, 0, &cpuid);
        printf("CPU %u APIC ID: 0x%x\n", i, cpuid.x.Register.Edx);
    }
    
    // Parse and display topology
    ParseCpu_ApicIdTopologyLayout();
    ParseCache_CpuidCacheExample();
    ParseTlb_CpuidTlbExample();
    
    return 0;
}
```

--------------------------------

### Command-Line Usage Examples

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/README.md

Demonstrates common command-line operations for the cpu_topology64.out utility, including displaying help, system topology, cache hierarchy, saving CPUID data, and analyzing saved data.

```bash
# Show help
./cpu_topology64.out H

# Display system topology via CPUID
./cpu_topology64.out C 1

# Display cache hierarchy
./cpu_topology64.out C 6

# Save system's CPUID to file
./cpu_topology64.out S my_system.cpuid

# Analyze saved CPUID on different machine
./cpu_topology64.out L my_system.cpuid 1
```

--------------------------------

### Validate CPU Domain Example

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/api-reference/cpuid-tools.md

Example of using Tools_IsDomainKnownEnumeration to check if a domain variable holds a valid CPU_DOMAIN value before proceeding.

```c
unsigned int domain = CoreDomain;
if (Tools_IsDomainKnownEnumeration(domain)) {
    printf("Valid domain: %u\n", domain);
}
```

--------------------------------

### Example Output: Display CPUID Leafs

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/README.md

Demonstrates the output format when running the command to display CPUID leaf values for processor 0. This includes information about various CPUID leaves if they exist.

```text
> CPUIDTOPOLOGY C 2
Displaying CPUID Leafs 0, 1, 4, 0Bh, 018h, 01Fh if they exist
*******************************
Processor: 0
Leaf 00000000 Subleaf 0 EAX: 00000016 EBX; 756e6547 ECX: 6c65746e EDX; 49656e69
Leaf 00000001 Subleaf 0 EAX: 00050654 EBX; 00200800 ECX: fedaf387 EDX: bfebfbff
Leaf 00000004 Subleaf 0 EAX: 3c004121 EBX; 01c0003f ECX: 0000003f EDX: 00000000
Leaf 00000004 Subleaf 1 EAX: 3c004122 EBX; 01c0003f ECX: 0000003f EDX: 00000000
Leaf 00000004 Subleaf 2 EAX: 3c004143 EBX; 03c0003f ECX: 000003ff EDX: 00000000
Leaf 00000004 Subleaf 3 EAX: 3c07c163 EBX; 0280003f ECX: 00006fff EDX: 00000000
Leaf 00000004 Subleaf 4 EAX: 00000000 EBX; 00000000 ECX: 00000000 EDX: 00000000
Leaf 0000000b Subleaf 0 EAX: 00000001 EBX; 00000002 ECX: 00000100 EDX: 00000000
Leaf 0000000b Subleaf 1 EAX: 00000005 EBX; 0000001c ECX: 00000201 EDX: 00000000
Leaf 0000000b Subleaf 2 EAX: 00000000 EBX; 00000000 ECX: 00000002 EDX: 00000000
```

--------------------------------

### Example: Binding Thread to Processors and Reading CPUID

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/api-reference/os-specific.md

Demonstrates how to bind a thread to specific processors (0 and 1) using Os_SetAffinity and then read CPUID information on those processors. This is useful for testing or ensuring specific CPU operations.

```c
// Bind thread to processor 0
Os_SetAffinity(0);

CPUID_REGISTERS cpuid;
Os_Platform_Read_Cpuid(0x1F, 0, &cpuid);
// CPUID is read on processor 0

// Bind to processor 1
Os_SetAffinity(1);
Os_Platform_Read_Cpuid(0x1F, 0, &cpuid);
// CPUID is read on processor 1
```

--------------------------------

### Print System Processor Count and Iterate

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/api-reference/cpuid-tools.md

Shows how to get the number of logical processors and then use this count to iterate and potentially set affinity for each processor.

```c
unsigned int num_procs = Tools_GetNumberOfProcessors();
printf("System has %u logical processors\n", num_procs);

// Iterate over all processors
for (unsigned int i = 0; i < num_procs; i++) {
    Tools_SetAffinity(i);
    // Read processor-specific CPUID
}
```

--------------------------------

### Parse CPUID Many-Domain Example

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/MANIFEST.txt

Parses CPUID information to represent complex CPU topologies with multiple levels or domains.

```c
void ParseCpu_CpuidManyDomainExample(GLOBAL_DATA* data) {
    // Implementation for parsing CPUID into a multi-domain hierarchy.
}
```

--------------------------------

### Parse CPUID Three-Domain Example

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/MANIFEST.txt

Parses CPUID information to represent a three-level CPU topology (e.g., Package, Core, Thread).

```c
void ParseCpu_CpuidThreeDomainExample(GLOBAL_DATA* data) {
    // Implementation for parsing CPUID into a three-domain hierarchy.
}
```

--------------------------------

### Cache and TLB Discovery Integration Example

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/api-reference/cache-tlb-parsing.md

This C code demonstrates how to safely check for CPUID leaf support before calling cache and TLB enumeration functions. It includes prerequisite checks for CPUID leaf 4 (cache) and leaf 18H (TLB).

```c
#include "cpuid_topology.h"

// Check CPUID support
CPUID_REGISTERS cpuid_max;
Tools_ReadCpuid(0, 0, &cpuid_max);

if (cpuid_max.x.Register.Eax >= 4) {
    printf("=== Cache Hierarchy ===\n");
    ParseCache_CpuidCacheExample();
} else {
    printf("CPUID leaf 4 not available\n");
}

if (cpuid_max.x.Register.Eax >= 0x18) {
    printf("\n=== TLB Hierarchy ===\n");
    ParseTlb_CpuidTlbExample();
} else {
    printf("CPUID leaf 18H not available\n");
}
```

--------------------------------

### Parse CPUID Legacy Example

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/MANIFEST.txt

Parses CPUID information using a legacy method. This might be used for compatibility with older systems or specific CPU features.

```c
void ParseCpu_CpuidLegacyExample(CPUID_REGISTERS* registers) {
    // Implementation for parsing CPUID using legacy methods.
}
```

--------------------------------

### Write CPUID to File Example

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/api-reference/file-io.md

This C code snippet demonstrates how to use `File_WriteCpuidToFile` to save the current system's CPUID information to a file. It includes error handling.

```c
if (File_WriteCpuidToFile("my_system.cpuid")) {
    printf("CPUID saved to my_system.cpuid\n");
} else {
    printf("Failed to save CPUID\n");
}
```

--------------------------------

### Read CPUID from File Example

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/api-reference/file-io.md

This C code snippet shows how to use `File_ReadCpuidFromFile` to load CPUID data from a file. It checks the return value to determine success or failure.

```c
if (File_ReadCpuidFromFile("cpuid_dump.txt")) {
    printf("Loaded CPUID from file\n");
    unsigned int num_procs = Tools_GetNumberOfProcessors();
    printf("File contains %u processors\n", num_procs);
} else {
    printf("Failed to read CPUID file\n");
}
```

--------------------------------

### Common Usage Sequence: Analyze Local System

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/api-reference/INDEX.md

This sequence demonstrates the typical steps to initialize the library, query system processor count, parse CPU topology, and then parse cache and TLB information for the local system.

```c
#include "cpuid_topology.h"

int main() {
    // Initialize
    CpuidTopology_InitGlobal();
    
    // Query basic info
    unsigned int num_procs = Tools_GetNumberOfProcessors();
    printf("System has %u processors\n", num_procs);
    
    // Parse topology
    ParseCpu_ApicIdTopologyLayout();
    
    // Parse caches and TLBs
    ParseCache_CpuidCacheExample();
    ParseTlb_CpuidTlbExample();
    
    return 0;
}
```

--------------------------------

### Get Number of Processors (Linux)

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/MANIFEST.txt

Queries the OS for the number of processors on Linux using sysinfo.h.

```c
#ifdef __linux__
#include <sysinfo.h>
static inline uint32_t Os_GetNumberOfProcessors() {
    return (uint32_t)sysconf(_SC_NPROCESSORS_ONLN);
}
#endif
```

--------------------------------

### Get Number of Logical Processors

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/api-reference/cpuid-tools.md

Retrieves the total count of logical processors available to the application. This can be used to iterate over all processors.

```c
unsigned int Tools_GetNumberOfProcessors(void)
```

--------------------------------

### Git Commit Sign-off Example

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/CONTRIBUTING.md

This is the required format for the sign-off line in your git commit messages. Ensure you use your real name.

```git
Signed-off-by: Joe Smith <joe.smith@email.com>
```

--------------------------------

### Display Command-Line Help

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/api-reference/display.md

Prints formatted help messages to stdout, detailing available command-line options and supported commands. This is useful when the program is run without arguments, with invalid options, or with missing arguments.

```c
void Display_DisplayParameters(void)
```

```c
Display_DisplayParameters();
// Output:
// Processor Topology Example.
//    Command Line Options:
//
//       H                  - Display this message
//       S [File]           - Saves raw CPUID to a file.
//       L [File] [COMMAND] - Loads raw CPUID from a file and perform a numbered COMMAND.
//       C [COMMAND]        - Execute the numbered command from below.
//
//    List of commands
//       0 - Display the topology via OS APIs (Not valid with File Load)
//       ...
```

--------------------------------

### Help Command Syntax

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/api-reference/main-entry-point.md

Displays command-line help and available commands. Use this option when you need a quick reference for program usage.

```bash
program H
```

--------------------------------

### Display Help Message

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/README.md

Shows the available command-line options for the CPUIDTOPOLOGY tool.

```bash
    Processor Topology Example.
       Command Line Options:

          H                  - Display this message
          S [File]           - Saves raw CPUID to a file.
          L [File] [COMMAND] - Loads raw CPUID from a file and perform a numbered COMMAND.
          C [COMMAND]        - Execute the numbered command from below.

       List of commands
          0 - Display the topology via OS APIs (Not valid with File Load)
          1 - Display the topology via CPUID
          2 - Display CPUID Leaf values one processor
          3 - Display CPUID Leaf values all processors
          4 - Display APIC ID layout
          5 - Display TLB Information
          6 - Display Cache Information
```

--------------------------------

### Main Entry Point and CLI

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/DOCUMENTATION_SUMMARY.md

Provides the main entry point for the command-line tool and its associated functionalities.

```APIDOC
## Main Entry Point and CLI

### Description
Provides the CLI and main() entry point for the topology enumeration tool.

### Usage
- **CLI**: Command-line interface for various analysis commands.
- **main()**: The main function for program execution.
```

--------------------------------

### Get Number of Processors (Linux)

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/api-reference/os-specific.md

Retrieves the number of logical processors available to the current process on Linux using `get_nprocs()`. It respects cgroup restrictions.

```c
NumberOfProcessors = (unsigned int)get_nprocs();
```

--------------------------------

### Program Entry Point

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/api-reference/main-entry-point.md

The main function serves as the program's entry point. It handles command-line arguments to either display help or initialize CPUID mode and dispatch commands.

```c
int main(int argc, char **argv)
```

--------------------------------

### Initialize Global CPUID Mode

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/api-reference/main-entry-point.md

Initializes the global CPUID mode by setting UseNativeCpuid to BOOL_TRUE. This is typically called at the start of the program when using native CPUID.

```c
CpuidTopology_InitGlobal()  // Sets UseNativeCpuid = BOOL_TRUE
```

--------------------------------

### Command-Line Interface

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/DOCUMENTATION_SUMMARY.md

Details the program's entry point, command-line syntax, and available commands for displaying topology information.

```APIDOC
## Command-Line Interface

### Description
Details the program's entry point, command-line syntax, and available commands for displaying topology information.

### Entry Point
- **int main(int argc, char **argv)**

### Syntax
Command-line syntax: Options H, S, L, C.

### Commands
Commands 0–6 with detailed output examples.

### State Management
Covers global state initialization and management.

### Compilation
Includes compilation instructions for Linux/Windows.
```

--------------------------------

### Get Number of Processors (Windows)

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/api-reference/os-specific.md

Retrieves the number of active processors across all processor groups on Windows using `GetActiveProcessorCount()`. This function is suitable for systems with more than 64 CPUs.

```c
NumberOfProcessors = GetActiveProcessorCount(ALL_PROCESSOR_GROUPS);
```

--------------------------------

### Load CPUID Data and Execute Command

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/README.md

Loads raw CPUID data from a file and executes a specified command (1-6) on that data.

```bash
    CPUIDTOPOLOGY L MyMachine.DAT 1
    CPUIDTOPOLOGY L MyMachine.DAT 2
    CPUIDTOPOLOGY L MyMachine.DAT 3
    CPUIDTOPOLOGY L MyMachine.DAT 4
    CPUIDTOPOLOGY L MyMachine.DAT 5
    CPUIDTOPOLOGY L MyMachine.DAT 6
```

--------------------------------

### Iterate and Read CPUID with SetAffinity

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/api-reference/cpuid-tools.md

Demonstrates iterating through all logical processors, setting affinity for each, and reading specific CPUID information.

```c
unsigned int num_procs = Tools_GetNumberOfProcessors();

for (unsigned int i = 0; i < num_procs; i++) {
    Tools_SetAffinity(i);
    CPUID_REGISTERS cpuid;
    Tools_ReadCpuid(0x1F, 0, &cpuid);
    printf("Processor %u APIC ID: 0x%x\n", i, cpuid.x.Register.Edx);
}
```

--------------------------------

### Load CPUID and Execute Command

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/api-reference/main-entry-point.md

Loads CPUID data from a file and executes a specified command on that simulated data. This allows for testing with pre-recorded CPUID information.

```bash
program L <filename> <command>
```

```bash
./cpu_topology64.out L my_system.cpuid 1
# Output: CPUID loaded from my_system.cpuid
#         [Topology via CPUID output]
```

--------------------------------

### File Structure of Documentation

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/DOCUMENTATION_SUMMARY.md

Illustrates the organization of documentation files for the Intel Processor Topology Enumeration library, including the main summary, README, types, and API reference sections.

```text
output/
├── DOCUMENTATION_SUMMARY.md      (this file)
├── README.md                     (architecture and overview)
├── types.md                      (data structures and enumerations)
└── api-reference/
    ├── INDEX.md                  (complete API index)
    ├── cpuid-tools.md            (core utilities)
    ├── file-io.md                (persistence)
    ├── display.md                (console output)
    ├── topology-parsing.md       (CPU topology)
    ├── cache-tlb-parsing.md      (hardware resources)
    ├── os-specific.md            (platform implementations)
    └── main-entry-point.md       (CLI and entry point)
```

--------------------------------

### Display_DisplayParameters

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/api-reference/display.md

Displays command-line help and usage information for the application. This function prints a formatted help message to stdout, detailing available command-line options and commands.

```APIDOC
## Display_DisplayParameters

### Description
Displays command-line help and usage information.

### Method
(void)

### Parameters
(none)

### Response
#### Success Response
Prints a formatted help message to stdout showing all available command-line options and supported commands.

### Request Example
```c
Display_DisplayParameters();
```

### Response Example
```text
Processor Topology Example.
   Command Line Options:

      H                  - Display this message
      S [File]           - Saves raw CPUID to a file.
      L [File] [COMMAND] - Loads raw CPUID from a file and perform a numbered COMMAND.
      C [COMMAND]        - Execute the numbered command from below.

   List of commands
      0 - Display the topology via OS APIs (Not valid with File Load)
      ...
```
```

--------------------------------

### Simulated CPUID Reading from File

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/README.md

Illustrates loading simulated CPUID data from a text file. This method is used when native CPUID reading is not desired or possible.

```C
File_ReadCpuidFromFile("file.cpuid")

```

--------------------------------

### Display OS Topology (Windows)

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/MANIFEST.txt

Shows OS-provided topology on Windows using GetLogicalProcessorInformationEx() for cache, core, and package info.

```c
#ifdef _WIN32
#include <windows.h>
#include <stdio.h>
static inline void Os_DisplayTopology() {
    SYSTEM_LOGICAL_PROCESSOR_INFORMATION_EX* buffer = NULL;
    DWORD bufferSize = 0;
    if (GetLogicalProcessorInformationEx(RelationAll, buffer, &bufferSize) == FALSE) {
        if (GetLastError() != ERROR_INSUFFICIENT_BUFFER) {
            printf("Error in GetLogicalProcessorInformationEx");
            return;
        }
        buffer = (SYSTEM_LOGICAL_PROCESSOR_INFORMATION_EX*)malloc(bufferSize);
        if (buffer == NULL) {
            printf("Error allocating memory");
            return;
        }
        if (GetLogicalProcessorInformationEx(RelationAll, buffer, &bufferSize) == FALSE) {
            printf("Error in GetLogicalProcessorInformationEx (2)");
            free(buffer);
            return;
        }
    }
    SYSTEM_LOGICAL_PROCESSOR_INFORMATION_EX* ptr = buffer;
    while (true) {
        switch (ptr->Relationship) {
            case RelationCache:
                printf("  Cache: Level %d, Type %s, Size %u\n", ptr->Cache.Level, ptr->Cache.Type == CacheData ? "Data" : (ptr->Cache.Type == CacheInstruction ? "Instruction" : "Unified"), ptr->Cache.Size);
                break;
            case RelationProcessorCore:
                printf("  Core: LogicalProcessorCount %u\n", ptr->ProcessorCore.LogicalProcessorCount);
                break;
            case RelationProcessorPackage:
                printf("  Package: LogicalProcessorCount %u\n", ptr->ProcessorPackage.LogicalProcessorCount);
                break;
            default:
                break;
        }
        if (ptr->NextEntryOffset == 0) break;
        ptr = (SYSTEM_LOGICAL_PROCESSOR_INFORMATION_EX*)((char*)ptr + ptr->NextEntryOffset);
    }
    free(buffer);
}
#endif
```

--------------------------------

### Display Help Text

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/MANIFEST.txt

Shows the help text for the utility. This function is typically called to provide usage instructions to the user.

```c
void Display_DisplayParameters() {
    // Implementation to display help text and parameters.
}
```

--------------------------------

### Topology Discovery with CPUID 0xB

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/README.md

Explains the fallback method for topology discovery using CPUID leaf 0xB, which provides basic domain information. This is used when 0x1F is not available.

```C
Fall back to CPUID 0xB (basic domains)

```

--------------------------------

### Display OS Topology (Linux)

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/MANIFEST.txt

Shows OS-provided topology on Linux by displaying /proc/cpuinfo.

```c
#ifdef __linux__
#include <stdio.h>
static inline void Os_DisplayTopology() {
    FILE* fp = fopen("/proc/cpuinfo", "r");
    if (fp) {
        char line[256];
        while (fgets(line, sizeof(line), fp)) {
            printf("%s", line);
        }
        fclose(fp);
    }
}
#endif
```

--------------------------------

### Safe CPUID Usage for Extended Topology

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/README.md

Demonstrates how to safely check for extended topology availability using CPUID leaf 0x1F and fall back to other methods if not supported.

```c
CPUID_REGISTERS cpuid;
Tools_ReadCpuid(0, 0, &cpuid);

// Check if extended topology is available
if (cpuid.x.Register.Eax >= 0x1F) {
    // Safe to use leaf 0x1F
} else {
    // Use leaf 0xB or fall back to legacy
}
```

--------------------------------

### Save and Load CPUID Data

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/api-reference/INDEX.md

Demonstrates saving the current system's CPUID data to a file and then loading it on another system. Loading CPUID data from a file allows subsequent reads to use the loaded data.

```c
#include "cpuid_topology.h"

// On first system
if (File_WriteCpuidToFile("system.cpuid")) {
    printf("Saved\n");
}

// On another system
if (File_ReadCpuidFromFile("system.cpuid")) {
    printf("Loaded\n");
    // All subsequent CPUID reads use file data
    ParseCpu_ApicIdTopologyLayout();
}
```

--------------------------------

### Compile with MSVC on Windows

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/README.md

Compiles the library and tools on Windows using MSVC, linking all necessary source files.

```cmd
cl cpuid_topology.c cpuid_topology_tools.c cpuid_topology_display.c ^
   cpuid_topology_file.c cpuid_topology_parsecpu.c ^
   cpuid_topology_parsecachetlb.c win_os_util.c ^
   /Fe:cpu_topology64.exe
```

--------------------------------

### Topology Discovery with CPUID 0x1 and 0x4

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/README.md

Describes the legacy method for topology discovery using CPUID leaves 0x1 and 0x4. This is used as a last resort when newer leaves are unavailable.

```C
Fall back to CPUID.1 + CPUID.4 (legacy)

```

--------------------------------

### Load CPUID Data from File for Offline Analysis

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/README.md

Loads CPUID information from 'cpuid_dump.txt' and then uses the loaded data for topology and cache analysis.

```c
#include "cpuid_topology.h"

void analyze_offline() {
    // On system B (or later)
    if (File_ReadCpuidFromFile("cpuid_dump.txt")) {
        printf("Loaded CPUID from file\n");
        
        // Now all CPUID queries return file data
        ParseCpu_ApicIdTopologyLayout();
        ParseCache_CpuidCacheExample();
    }
}
```

--------------------------------

### Compile with GCC on Linux

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/README.md

Compiles the library and tools on Linux using GCC, linking all necessary source files.

```bash
gcc -g -Wall \
    cpuid_topology.c \
    cpuid_topology_tools.c \
    cpuid_topology_display.c \
    cpuid_topology_file.c \
    cpuid_topology_parsecpu.c \
    cpuid_topology_parsecachetlb.c \
    linux_os_util.c \
    -o cpu_topology64
```

--------------------------------

### Display Topology via OS APIs

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/api-reference/main-entry-point.md

Displays processor topology information by querying the operating system's APIs. This command is only available in native mode and requires OS-specific calls.

```bash
program C 0
```

```bash
./cpu_topology64.out C 0
# Output: processor   : 0
#         vendor_id   : GenuineIntel
#         cpu family  : 6
#         model       : 165
#         model name  : Intel(R) Core(TM) i9-10900K CPU @ 3.70GHz
#         ...

```

--------------------------------

### ParseCpu_CpuidManyDomainExample

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/api-reference/topology-parsing.md

Parses CPU topology for systems with more than three CPU domains. Enumerates all distinct CPU topology domains, including modern hierarchies with tiles, modules, and die groups. It extracts domain type and bit shift for each subleaf, validates against known types, and for unknown domains, uses the shift of the previous domain. It builds a matrix of masks for global and relative APIC ID extraction and populates an `APICID_BIT_LAYOUT_CTX` structure with shift values, domain types, masks, and package domain index. Displays the full topology. Supports all modern Intel domain levels: Logical Processor, Core, Module, Tile, Die, and Die Group (Package).

```APIDOC
## void ParseCpu_CpuidManyDomainExample(unsigned int Leaf)

### Description
Enumerates all distinct CPU topology domains including modern hierarchies with tiles, modules, and die groups. For each subleaf, it extracts domain type from ECX bits 15:8 and domain bit shift from EAX bits 4:0. It validates the domain against known types: InvalidDomain, LogicalProcessorDomain, CoreDomain, ModuleDomain, TileDomain, DieDomain, DieGrpDomain. For unknown domains, it uses the shift of the previous domain (collapses unknown levels). It builds a matrix of masks for global and relative APIC ID extraction. Populates an `APICID_BIT_LAYOUT_CTX` structure with shift values for each known domain, domain type for each shift, masks for extracting domain IDs globally and relative to parent domains, and the package domain index. Displays the full topology via `Display_ManyDomainExample()`. Supports all modern Intel domain levels: Logical Processor, Core, Module, Tile, Die, and Die Group (Package).

### Function Signature
void ParseCpu_CpuidManyDomainExample(unsigned int Leaf)

### Parameters
#### Function Parameters
- **Leaf** (unsigned int) - Required - CPUID leaf number (0xB or 0x1F; 0x1F required for >3 domains)

### Example
```c
// For Intel Ice Lake and newer with complex topologies
ParseCpu_CpuidManyDomainExample(0x1F);
// Outputs all topology levels with bit shift information
```

### Return Type
void
```

--------------------------------

### Save CPUID Data to File

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/README.md

Saves the current system's raw CPUID information to a specified file for later use.

```bash
    CPUIDTOPOLOGY S MyMachine.DAT
```

--------------------------------

### Execute Local System Commands

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/README.md

Runs commands 0 through 6 on the local system's CPUID to display various topology and CPU information.

```bash
    CPUIDTOPOLOGY C 0
    CPUIDTOPOLOGY C 1
    CPUIDTOPOLOGY C 2
    CPUIDTOPOLOGY C 3
    CPUIDTOPOLOGY C 4
    CPUIDTOPOLOGY C 5
    CPUIDTOPOLOGY C 6
```

--------------------------------

### Display and Console Output

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/api-reference/INDEX.md

Functions for displaying various CPU topology and configuration details to the console.

```APIDOC
## Display_DisplayParameters

### Description
Show help text and usage information for the library's parameters.

### Signature
`void Display_DisplayParameters(void)`

## Display_DisplayProcessorLeafs

### Description
Display the raw CPUID values for all processors on the system.

### Signature
`void Display_DisplayProcessorLeafs(unsigned int NumberOfProcessors)`

## Display_ApicIdBitLayout

### Description
Display the bit layout of APIC IDs, illustrating how different topology levels are encoded.

### Signature
`void Display_ApicIdBitLayout(PAPICID_BIT_LAYOUT_CTX pApicidBitLayoutCtx)`

## Display_ThreeDomainDisplay

### Description
Display the three-domain CPU topology, including package and logical processor shifts.

### Signature
`void Display_ThreeDomainDisplay(unsigned int Leaf, unsigned int PackageShift, unsigned int LogicalProcessorShift)`

## Display_DisplayProcessorCaches

### Description
Display detailed information about the caches present on the processors.

### Signature
`void Display_DisplayProcessorCaches(PCPUID_CACHE_INFO pCacheInfo, unsigned int NumberOfCaches)`

## Display_DisplayProcessorTlbs

### Description
Display detailed information about the Translation Lookaside Buffers (TLBs) present on the processors.

### Signature
`void Display_DisplayProcessorTlbs(PCPUID_TLB_INFO pTlbInfo, unsigned int NumberOfTlbs)`

## Display_ManyDomainExample

### Description
Show an example of a multi-domain CPU topology, illustrating complex hierarchical structures.

### Signature
`void Display_ManyDomainExample(unsigned int Leaf, PAPICID_BIT_LAYOUT_CTX pApicidBitLayoutCtx)`
```

--------------------------------

### Display Topology via CPUID

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/api-reference/main-entry-point.md

Performs comprehensive topology enumeration using modern and legacy CPUID leaves. It displays information in three-domain and many-domain views.

```bash
program C 1
```

```bash
program L file.cpuid 1
```

--------------------------------

### Display Three-Domain CPU Topology

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/api-reference/display.md

Displays a simplified three-level CPU topology (logical processor, core, package). Use when systems do not have complex domain hierarchies.

```c
void Display_ThreeDomainDisplay(unsigned int Leaf, unsigned int PackageShift, unsigned int LogicalProcessorShift)
```

```c
Display_ThreeDomainDisplay(0x1F, 5, 1);
// Displays topology with 5-bit shift for package and 1-bit shift for LP domain
```

--------------------------------

### Native CPUID Reading (Linux)

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/README.md

Demonstrates how the library reads CPUID information on Linux using assembly instructions. This is part of the native CPUID reading data flow.

```Assembly
asm "CPUID"

```

--------------------------------

### Parse CPU Topology using Legacy CPUID Leaves

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/api-reference/topology-parsing.md

Parses CPU topology using legacy CPUID leaves 1 and 4. This method is for historical reference and may not accurately represent modern complex topologies.

```c
void ParseCpu_CpuidLegacyExample(void)
{
    ParseCpu_CpuidLegacyExample();
    // Outputs topology for old systems using CPUID.1 and CPUID.4
}
```

--------------------------------

### Read CPUID Instruction (Windows)

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/MANIFEST.txt

Demonstrates how to read the CPUID instruction on Windows using the MSVC __cpuidex intrinsic.

```c
#ifdef _WIN32
static inline void Os_Platform_Read_Cpuid(uint32_t leaf, uint32_t subleaf, uint32_t regs[4]) {
    int info[4];
    __cpuidex(info, leaf, subleaf);
    regs[0] = info[0];
    regs[1] = info[1];
    regs[2] = info[2];
    regs[3] = info[3];
}
#endif
```

--------------------------------

### Execute Command on Native CPUID

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/api-reference/main-entry-point.md

Executes a specified command using the native system's CPUID information. This is the default mode for direct system analysis.

```bash
program C <command>
```

```bash
./cpu_topology64.out C 1
# Output: [Topology via CPUID]
```

--------------------------------

### Execute 'cat /proc/cpuinfo' on Linux

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/api-reference/os-specific.md

Executes the 'cat /proc/cpuinfo' command using the system() function to display detailed processor information on Linux systems. This is part of the Os_DisplayTopology implementation for Linux.

```c
system("cat /proc/cpuinfo\n");
```

--------------------------------

### ParseCpu_CpuidLegacyExample

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/api-reference/topology-parsing.md

Parses CPU topology using legacy CPUID leaves 1 and 4 (pre-Leaf 0xB). Implements the historical topology enumeration method using CPUID leaf 1 and 4 to determine logical processors per core, logical processors per package, and bit shifts for core and package domains. Displays the three-domain topology. Note: This method is superseded by leaves 0xB and 0x1F and cannot accurately represent complex modern topologies.

```APIDOC
## void ParseCpu_CpuidLegacyExample(void)

### Description
Parses CPU topology using legacy CPUID leaves 1 and 4 (pre-Leaf 0xB). Implements the historical topology enumeration method using CPUID leaf 1 to determine maximum addressable IDs for logical processors in a physical package and HTT support, and CPUID leaf 4 to determine maximum addressable IDs for cores. Uses these values to calculate logical processors per core, logical processors per package, and bit shifts for core and package domains. Displays the three-domain topology via `Display_ThreeDomainDisplay()`. Note: This method is superseded by leaves 0xB (Ivy Bridge+) and 0x1F (Ice Lake+). It is shown primarily for historical/compatibility reference and cannot accurately represent complex modern topologies.

### Function Signature
void ParseCpu_CpuidLegacyExample(void)

### Parameters
#### Function Parameters
- **(none)** (—) - — - —

### Example
```c
ParseCpu_CpuidLegacyExample();
// Outputs topology for old systems using CPUID.1 and CPUID.4
```

### Return Type
void
```

--------------------------------

### Compile Linux Application

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/api-reference/main-entry-point.md

Compile the Linux application using GCC. This involves compiling individual source files into object files and then linking them to create the final executable.

```bash
gcc -g -c -Wall linux_os_util.c
gcc -g -c -Wall cpuid_topology_display.c
gcc -g -c -Wall cpuid_topology_file.c
gcc -g -c -Wall cpuid_topology_parsecachetlb.c
gcc -g -c -Wall cpuid_topology_parsecpu.c
gcc -g -c -Wall cpuid_topology_tools.c
gcc -g cpuid_topology.c -Wall -o cpu_topology64.out \
    linux_os_util.o cpuid_topology_display.o cpuid_topology_file.o \
    cpuid_topology_parsecachetlb.o cpuid_topology_parsecpu.o cpuid_topology_tools.o
```

--------------------------------

### Persistence API

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/DOCUMENTATION_SUMMARY.md

Enables loading and saving CPUID dumps to and from files, with a defined file format specification.

```APIDOC
## Persistence API

### Description
Enables loading and saving CPUID dumps to and from files, with a defined file format specification.

### Functions
- **File_ReadCpuidFromFile()** – Load CPUID dump
- **File_WriteCpuidToFile()** – Save CPUID dump

### File Format
Specification includes L/S/A directives, with examples and round-trip patterns.
```

--------------------------------

### Topology Discovery with CPUID 0x1F

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/README.md

Details the process of discovering processor topology using CPUID leaf 0x1F, which provides information on all domains. This is the preferred method.

```C
CPUID 0x1F (preferred, all domains)

```

--------------------------------

### Display_ManyDomainExample

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/api-reference/display.md

Displays topology information for systems with many CPU domains, using the full domain bit layout context to show complex hierarchies beyond the three-level model.

```APIDOC
## Display_ManyDomainExample

### Description
Displays topology information for systems with many CPU domains.

### Method
```c
void Display_ManyDomainExample(unsigned int Leaf, PAPICID_BIT_LAYOUT_CTX pApicidBitLayoutCtx)
```

### Parameters
#### Path Parameters
- **Leaf** (unsigned int) - Yes - CPUID leaf (0xB or 0x1F)
- **pApicidBitLayoutCtx** (PAPICID_BIT_LAYOUT_CTX) - Yes - Pointer to bit layout context populated by parsing

### Response
#### Return Type
void

### Description
Displays topology for systems with complex domain hierarchies beyond the simple three-level model. Uses the full domain bit layout context to show how APIC IDs encode multiple topology dimensions (logical processors, cores, modules, tiles, dies, die groups). This is used when CPUID leaf 0x1F indicates multiple distinct domain types.

### Example
```c
APICID_BIT_LAYOUT_CTX ctx = {0};
// ... populate via ParseCpu_CpuidManyDomainExample() ...
Display_ManyDomainExample(0x1F, &ctx);
// Displays all topology levels including tiles, modules, etc.
```
```

--------------------------------

### Parse CPU Topology using Three-Domain CPUID Leaves

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/api-reference/topology-parsing.md

Parses CPU topology for three-level domain hierarchies using modern CPUID leaves (0xB or 0x1F). This method is suitable for systems with logical processor, core, and package/die group levels.

```c
CPUID_REGISTERS cpuid0;
Tools_ReadCpuid(0, 0, &cpuid0);

if (cpuid0.x.Register.Eax >= 0x1F) {
    ParseCpu_CpuidThreeDomainExample(0x1F);
} else if (cpuid0.x.Register.Eax >= 0xB) {
    ParseCpu_CpuidThreeDomainExample(0xB);
}
```

--------------------------------

### Save CPUID Data to File

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/README.md

Saves the current CPUID information to a file named 'cpuid_dump.txt' for later offline analysis.

```c
#include "cpuid_topology.h"

void save_for_analysis() {
    // On system A
    if (File_WriteCpuidToFile("cpuid_dump.txt")) {
        printf("Saved to cpuid_dump.txt\n");
    }
}
```

--------------------------------

### File I/O Functions

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/DOCUMENTATION_SUMMARY.md

Functions for persisting CPUID data to files and loading it back.

```APIDOC
## File I/O

### Description
Functions for saving and loading CPUID data to and from files.

### Functions
- **File_***: Functions for file input/output operations.
```

--------------------------------

### Core Utilities

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/DOCUMENTATION_SUMMARY.md

Provides essential functions for interacting with CPUID, processor counts, thread affinity, and APIC IDs.

```APIDOC
## Core Utilities

### Description
Provides essential functions for interacting with CPUID, processor counts, thread affinity, and APIC IDs.

### Functions
- **Tools_ReadCpuid()** – Read CPUID (native or simulated)
- **Tools_GetNumberOfProcessors()** – Query processor count
- **Tools_SetAffinity()** – Bind thread to processor
- **Tools_GatherPlatformApicIds()** – Collect APIC IDs
- **Tools_CreateTopologyShift()** – Compute domain bit shifts
- **Tools_IsNative()** – Check CPUID mode
- **Tools_IsDomainKnownEnumeration()** – Validate domain types
```

--------------------------------

### File I/O

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/api-reference/INDEX.md

Functions for reading and writing CPUID information to and from files.

```APIDOC
## File_ReadCpuidFromFile

### Description
Load CPUID information from a specified file.

### Signature
`BOOL_TYPE File_ReadCpuidFromFile(char *pszFileName)`

## File_WriteCpuidToFile

### Description
Save the current CPUID information to a specified file.

### Signature
`BOOL_TYPE File_WriteCpuidToFile(char *pszFileName)`
```

--------------------------------

### Print Gathered APIC IDs

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/api-reference/cpuid-tools.md

Demonstrates how to call Tools_GatherPlatformApicIds to populate an array with APIC IDs and then iterate through the populated IDs to print them.

```c
unsigned int apic_ids[MAX_PROCESSORS];
unsigned int num_apic_ids = Tools_GatherPlatformApicIds(apic_ids, MAX_PROCESSORS);

for (unsigned int i = 0; i < num_apic_ids; i++) {
    printf("Processor %u: APIC ID = 0x%08x\n", i, apic_ids[i]);
}
```

--------------------------------

### Compile Linux CPU Topology Enumeration

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/README.md

Compile the OS-agnostic and OS-dependent C source files for the CPU topology enumeration tool on Linux using GCC. This command links all object files into an executable named cpu_topology64.out.

```bash
gcc -g -c -Wall linux_os_util.c
gcc -g -c -Wall cpuid_topology_display.c
gcc -g -c -Wall cpuid_topology_file.c
gcc -g -c -Wall cpuid_topology_parsecachetlb.c
gcc -g -c -Wall cpuid_topology_parsecpu.c
gcc -g -c -Wall cpuid_topology_tools.c
gcc -g  cpuid_topology.c -Wall -o cpu_topology64.out linux_os_util.o cpuid_topology_display.o cpuid_topology_file.o cpuid_topology_parsecachetlb.o  cpuid_topology_parsecpu.o cpuid_topology_tools.o
```

--------------------------------

### File_ReadCpuidFromFile

Source: https://github.com/intel/sdm-processor-topology-enumeration/blob/main/_autodocs/api-reference/file-io.md

Loads CPUID data from a previously saved file and switches to simulated mode. It parses the file content and populates internal simulation structures, automatically setting the system to use simulated CPUID data.

```APIDOC
## File_ReadCpuidFromFile

### Description
Loads CPUID data from a previously saved file and switches to simulated mode.

### Method
```c
BOOL_TYPE File_ReadCpuidFromFile(char *pszFileName)
```

### Parameters
#### Path Parameters
- **pszFileName** (char *) - Yes - -	Path to CPUID data file

### Return Type
BOOL_TYPE

### Returns
BOOL_TRUE on successful read, BOOL_FALSE if file cannot be opened or parsing fails.

### Description
Opens the specified file and parses CPUID data according to the file format above. Populates the global CPUID simulation structures: `SimulatedCpuid[][]` for most leaves, `SimulatedCpuidLeaf4[][]` for per-processor cache information, `SimulatedCpuidLeaf18[][]` for per-processor TLB information, `SimulatedApicIds[]` for processor APIC IDs, and `NumberOfSimulatedProcessors` with the count of processors loaded. Upon successful open, automatically sets `UseNativeCpuid` to BOOL_FALSE, causing all subsequent `Tools_ReadCpuid()` calls to return simulated data.

Error conditions:
- File cannot be opened (permissions, missing file)
- Invalid format (malformed lines, out-of-range indices)
- Exceeds MAX_PROCESSORS capacity

The function prints diagnostic output for successful and skipped entries.

### Example
```c
if (File_ReadCpuidFromFile("cpuid_dump.txt")) {
    printf("Loaded CPUID from file\n");
    unsigned int num_procs = Tools_GetNumberOfProcessors();
    printf("File contains %u processors\n", num_procs);
} else {
    printf("Failed to read CPUID file\n");
}
```
```