Implementation:Ggml org Ggml Sycl common

Knowledge Sources	GGML
Domains	ML_Infrastructure, GPU_Compute, Hardware_Abstraction
Last Updated	2025-05-15 12:00 GMT

Overview

Central shared header for the SYCL backend, providing common types, macros, constants, structures, and utility declarations used by all SYCL kernel files.

Description

common.hpp is the single most-included header across the entire SYCL backend. It aggregates all foundational dependencies -- the DPCT helper layer, SYCL headers, hardware presets, and ggml-common types -- into a unified interface. The file defines:

• Debug and error macros: GGML_SYCL_DEBUG for conditional debug logging, CHECK_TRY_ERROR for exception-safe SYCL calls, and SYCL_CHECK for fatal error reporting.
• Hardware version constants: VER_4VEC, VER_GEN9, VER_GEN12, VER_GEN13 for Intel GPU generation detection and optimization branching.
• Tuning parameters: GGML_SYCL_DMMV_X (32), GGML_SYCL_MMV_Y (1), MMQ_MAX_BATCH_SIZE (32), MMVQ_MAX_BATCH_SIZE (8) for kernel launch configuration.
• Type aliases: queue_ptr (sycl::queue *), dfloat/dfloat2 (float or sycl::half depending on GGML_SYCL_F16 flag).
• Core structures: sycl_device_info (compute capability, streaming multiprocessors, memory), ggml_sycl_device_info (multi-device array with tensor split ratios), ggml_backend_sycl_context (device id, queue streams, memory pool, scratch buffer), ggml_sycl_pool/ggml_sycl_pool_alloc (GPU memory pool management), and optimize_feature (reorder support flag).
• Conditional oneDNN support: When GGML_SYCL_DNNL is enabled, includes dnnl.hpp and dnnl_sycl.hpp for Intel oneDNN integration.

Usage

Every SYCL kernel source file includes this header as its primary dependency. It is not intended for direct use by external consumers; rather, it provides the shared infrastructure that all kernel implementations in the ggml-sycl directory rely upon.

Code Reference

Source Location

• Repository: GGML
• File: src/ggml-sycl/common.hpp
• Lines: 663

Signatures

// Host memory management
void* ggml_sycl_host_malloc(size_t size);
void ggml_sycl_host_free(void* ptr);

// Device selection
inline dpct::err0 ggml_sycl_set_device(const int device);
int get_current_device_id();

// Key type aliases
typedef sycl::queue *queue_ptr;
#ifdef GGML_SYCL_F16
typedef sycl::half dfloat;
typedef sycl::half2 dfloat2;
#else
typedef float dfloat;
typedef sycl::float2 dfloat2;
#endif

// GPU mode enumeration
enum ggml_sycl_backend_gpu_mode {
    SYCL_UNSET_GPU_MODE = -1,
    SYCL_SINGLE_GPU_MODE = 0,
    SYCL_MUL_GPU_MODE
};

I/O Contract

Inputs

Name	Type	Required	Description
(header)	-	-	No runtime inputs; provides compile-time types, macros, and declarations

Outputs

Name	Type	Description
(header)	-	Exports types, macros, structures, and function declarations for SYCL kernel files

Usage Examples

// Typical inclusion in a SYCL kernel file:
#include "common.hpp"

// Using the debug macro:
GGML_SYCL_DEBUG("Processing tensor %s on device %d\n", tensor->name, ctx.device);

// Using error checking:
SYCL_CHECK(CHECK_TRY_ERROR(stream->memcpy(dst, src, size)));

// Using the dfloat types for dequantization:
dfloat2 v;
dequantize_q4_0(vx, ib, iqs, v);
float result = v.x() + v.y();

Related Pages

Implements Principle

• Principle:Ggml_org_Ggml_SYCL_GPU_Computation
• Environment:Ggml_org_Ggml_C_Cpp_Build_Environment