Header Files

A function prototype declares a function's name, return type, and parameter types without providing its implementation. This allows the compiler to perform type checking and generate correct calling code when the function is used in other source files. For NPU SDKs, prototypes define the entry points to vendor runtime libraries, driver APIs, and optimized kernel libraries.

• Example: extern int npu_compute_tensor(const void* config, float* input, float* output);
• Purpose: Informs the compiler that npu_compute_tensor exists and will be linked later, enabling separate compilation.

Macros are preprocessor directives (#define) that perform text substitution before compilation. They are used for constants, inline code snippets, and conditional compilation. In hardware programming, macros define:

• Hardware Constants: Register addresses, buffer sizes, and status flags (e.g., #define NPU_REG_STATUS 0x1000).
• Platform Abstraction: Conditional code for different NPU generations or operating systems using #ifdef.
• Inline Operations: Simple, performance-critical operations mapped to vendor intrinsics.

Header files define custom data types and structures that model the hardware's data layout and API contracts. This is essential for ensuring binary compatibility between the application and the vendor's Application Binary Interface (ABI).

• Opaque Handles: Typedefs like typedef void* npu_device_handle_t hide implementation details.
• Configuration Structs: Packed structures that mirror hardware descriptor formats for kernel launches or memory transfers.
• Enumerations: Named constants for error codes, operation types, and hardware features (e.g., enum npu_data_format { FORMAT_FP16, FORMAT_INT8 };).

Intrinsics are compiler-specific functions that map directly to single or a few low-level machine instructions. Header files provided by the vendor SDK declare intrinsics for accessing specialized NPU operations like tensor cores or SIMD units.

• Function: Provide a C/C++ callable interface to Vendor ISA instructions without writing assembly.
• Example: A function like __npu_tensor_multiply_add(...) might compile directly to a proprietary NPU instruction.
• Benefit: Grants low-level performance control while maintaining portability across compiler versions.

Include guards prevent a header file's contents from being included multiple times in a single translation unit, which would cause redefinition errors. Conditional compilation directives tailor the header for different environments.

• Standard Guard: #ifndef NPU_KERNEL_H / #define NPU_KERNEL_H / #endif
• Pragma Once: A non-standard but widely supported alternative: #pragma once.
• Use Case: Guards are universal; conditional compilation (#ifdef TARGET_NPU_V2) selects between features for different hardware versions within the same header.

In C++, the extern "C" directive specifies that the declared functions should use C linkage and naming conventions. This is critical when header files wrap C-based vendor SDK libraries, ensuring the C++ compiler does not perform name mangling, which would break linking.

• Syntax: extern "C" { #include "vendor_npu.h" } or wrapping declarations within extern "C" { ... }.
• Purpose: Guarantees the linker can find the correctly named symbols in the vendor's pre-compiled static library or dynamic library.

The primary role of a header file is to declare function prototypes for the vendor's SDK. This tells the compiler the name, return type, and parameters of functions like npu_launch_kernel() or tensor_memory_alloc(), without exposing the implementation. This enables separate compilation—your application code compiles against the declarations, and the linker later resolves them to the pre-compiled vendor library binaries. It defines the Application Programming Interface (API) contract.

Header files define the custom data structures and constants that map to the accelerator's hardware. This includes:

• Tensor descriptors (dimensions, data type, layout).
• Enumerated types for operations (e.g., CONV_2D, MATMUL).
• Error codes specific to the hardware (NPU_SUCCESS, NPU_MEMORY_ERROR).
• Magic numbers like MAX_SIMD_WIDTH or SHARED_MEM_SIZE. Using these types ensures data is formatted correctly for the hardware's memory subsystem and instruction set.

For low-level performance, headers expose compiler intrinsics—special functions that map directly to single NPU instructions, such as a tensor load/store or a fused multiply-add. They also provide inline functions for common operations, giving the compiler a hint to insert the code directly at the call site to avoid function call overhead. This is critical for kernel fusion and exploiting specific hardware features like SIMD lanes or tensor cores without writing assembly.

Header files use preprocessor macros (#define) extensively for:

• Platform abstraction: #ifdef NPU_VENDOR_A / #elif defined(NPU_VENDOR_B) to conditionally include code for different accelerators.
• Feature flags: ENABLE_FP16_PRECISION to toggle support for mixed-precision.
• Constant folding: Defining TILE_SIZE as 32 allows the compiler to optimize loops unrolled for that size.
• Debugging: DEBUG_PRINT macros that compile to nothing in release builds. This enables a single codebase to target multiple NPU generations or vendors.

To prevent multiple inclusion errors, header files use include guards (#ifndef HEADER_NAME_H / #define HEADER_NAME_H / #endif) or the #pragma once directive. They also #include other necessary headers, creating a dependency graph. For example, npu_linear_ops.h might include npu_tensor_types.h. Proper structuring avoids circular dependencies and ensures the compiler has all necessary type definitions. This is vital for large SDKs with hundreds of interdependent headers.

Headers are the anchor point for Application Binary Interface (ABI) stability. Changes to function signatures or data structure layouts in a header break binary compatibility. Vendors use versioning macros (e.g., SDK_VERSION_MAJOR 2) and namespace isolation (via prefixing, like vendorx_) to manage evolution. Engineers must include the correct versioned header to match the linked runtime library. Mismatches cause subtle linking errors or runtime crashes.

A vendor-specific software development kit that provides the complete toolchain for programming a hardware accelerator. It includes:

• Header files (.h) defining function prototypes and data types.
• Static or dynamic libraries (.a, .so, .dll) containing the pre-compiled implementations.
• Compilers, debuggers, and profiling tools tailored for the target architecture.
• Documentation and code samples. For NPU development, the SDK abstracts the underlying Instruction Set Architecture (ISA) and provides high-level APIs for memory management, kernel launching, and synchronization.

Low-level programming constructs that map directly to specific machine instructions of the processor. In header files, intrinsics are declared as functions or special data types (e.g., __m256 for AVX). They provide controlled access to hardware features like:

• SIMD (Single Instruction, Multiple Data) operations.
• Tensor cores or dedicated matrix multiplication units.
• Specialized load/store instructions for NPU memory hierarchies. Using intrinsics allows developers to write performance-critical code in C/C++ without resorting to inline assembly, while still giving the compiler explicit instructions for code generation.

A specific class of hardware intrinsics that are provided and recognized by the compiler itself (e.g., GCC, Clang, ICC). These are declared in compiler-specific header files (like <xmmintrin.h> for SSE). Key characteristics:

• They are inlined by the compiler, replacing the function call with the exact machine instruction(s).
• They provide a portable way to access non-portable hardware features, as the compiler handles the mapping for the target architecture.
• They are essential for writing vectorized code that leverages NPU parallel processing units efficiently, as they expose low-level operations on vector data types.

A low-level contract that defines how different compiled modules interact. Header files are the source-level manifestation of the ABI. The ABI governs:

• Calling convention: How function arguments are passed (in registers or on the stack) and how values are returned.
• Data structure layout: The size, alignment, and padding of structs and classes.
• Name mangling: How function names are encoded in object files. For NPU programming, the vendor SDK must define a stable ABI. The header files ensure the compiler generates code that conforms to this ABI, enabling binaries to correctly call into the vendor's runtime libraries and kernel drivers.

These are the binary implementations referenced by declarations in header files.

Static Library (.a, .lib):

• Archived collection of object files.
• Linked at compile time; its code is copied directly into the final executable.
• Results in a larger binary but no runtime dependency.

Dynamic Library (.so, .dll, .dylib):

• Linked at runtime (load time).
• Multiple executables can share a single copy in memory.
• Allows for library updates without recompiling the main application.
• The header file prototypes tell the compiler what functions exist in the library, and the linker (for static) or loader (for dynamic) resolves the actual addresses.

The integrated set of tools used to build software for a specific NPU. Header files are a critical input to this toolchain.

• Cross-Compiler: Compiles code on a host system (e.g., x86) for the target NPU architecture. It uses the vendor's header files to understand the NPU's API.
• Assembler & Linker: Process object code, using linker scripts to define the NPU's memory map and relocation to adjust addresses.
• The toolchain consumes header files to perform type checking, inline expansion of intrinsics, and ensure ABI compliance before generating the final fat binary or NPU-specific executable.