lcpfs 2026.1.102

// Copyright 2025 LunaOS Contributors
// SPDX-License-Identifier: Apache-2.0
//
// Intel QAT FFI Bindings
// Raw bindings to Intel QuickAssist Technology userspace library (qatlib).
//
// Reference: Intel QAT Software Programmer's Guide
// Headers: qat/cpa.h, qat/cpa_dc.h, qat/cpa_cy_sym.h, qae_mem.h

//! Intel QAT FFI bindings - raw C API types and functions.
//!
//! These are low-level bindings to the Intel QAT userspace library.
//! Use the higher-level `lcpfs_qat` module for a safe Rust API.

#![allow(non_camel_case_types)]
#![allow(non_snake_case)]
#![allow(dead_code)]

use core::ffi::{c_char, c_int, c_uchar, c_uint, c_ulong, c_void};

// ═══════════════════════════════════════════════════════════════════════════════
// CPA TYPES (Common Performance Analytics)
// ═══════════════════════════════════════════════════════════════════════════════

/// CPA status codes returned by QAT API functions.
pub type CpaStatus = c_int;

/// Operation completed successfully.
pub const CPA_STATUS_SUCCESS: CpaStatus = 0;
/// Operation failed.
pub const CPA_STATUS_FAIL: CpaStatus = -1;
/// Operation should be retried (resource temporarily unavailable).
pub const CPA_STATUS_RETRY: CpaStatus = 1;
/// Insufficient resources to complete operation.
pub const CPA_STATUS_RESOURCE: CpaStatus = 2;
/// Invalid parameter passed to function.
pub const CPA_STATUS_INVALID_PARAM: CpaStatus = 3;
/// Fatal error occurred.
pub const CPA_STATUS_FATAL: CpaStatus = -2;
/// Operation is unsupported.
pub const CPA_STATUS_UNSUPPORTED: CpaStatus = -3;
/// Service is restarting.
pub const CPA_STATUS_RESTARTING: CpaStatus = 4;

/// CPA boolean type.
pub type CpaBoolean = c_uchar;

/// Boolean false value.
pub const CPA_FALSE: CpaBoolean = 0;
/// Boolean true value.
pub const CPA_TRUE: CpaBoolean = 1;

/// CPA instance handle (opaque)
pub type CpaInstanceHandle = *mut c_void;

/// Flat buffer for DMA operations
#[repr(C)]
#[derive(Debug, Clone, Copy)]
pub struct CpaFlatBuffer {
    /// Length of data in buffer
    pub dataLenInBytes: u32,
    /// Pointer to data (must be physically contiguous for DMA)
    pub pData: *mut u8,
}

/// Buffer list containing multiple flat buffers
#[repr(C)]
#[derive(Debug, Clone, Copy)]
pub struct CpaBufferList {
    /// Number of buffers in list
    pub numBuffers: u32,
    /// Private metadata (for driver use)
    pub pPrivateMetaData: *mut c_void,
    /// Array of flat buffers
    pub pBuffers: *mut CpaFlatBuffer,
}

/// Physical address type (for DMA)
pub type CpaPhysicalAddr = u64;

// ═══════════════════════════════════════════════════════════════════════════════
// DC (DATA COMPRESSION) TYPES
// ═══════════════════════════════════════════════════════════════════════════════

/// Compression session handle
pub type CpaDcSessionHandle = *mut c_void;

/// Compression algorithms supported by QAT.
#[repr(C)]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CpaDcCompType {
    /// DEFLATE compression (RFC 1951).
    CPA_DC_DEFLATE = 0,
    /// LZ4 compression.
    CPA_DC_LZ4 = 1,
    /// LZ4s (streaming) compression.
    CPA_DC_LZ4S = 2,
    /// ZSTD compression (QAT 2.0+).
    CPA_DC_ZSTD = 3,
}

/// Compression levels (1 = fastest, 9 = best compression).
#[repr(C)]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CpaDcCompLvl {
    /// Level 1 - fastest compression.
    CPA_DC_L1 = 1,
    /// Level 2.
    CPA_DC_L2 = 2,
    /// Level 3.
    CPA_DC_L3 = 3,
    /// Level 4.
    CPA_DC_L4 = 4,
    /// Level 5.
    CPA_DC_L5 = 5,
    /// Level 6.
    CPA_DC_L6 = 6,
    /// Level 7.
    CPA_DC_L7 = 7,
    /// Level 8.
    CPA_DC_L8 = 8,
    /// Level 9 - best compression ratio.
    CPA_DC_L9 = 9,
}

/// Huffman tree type for DEFLATE compression.
#[repr(C)]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CpaDcHuffType {
    /// Static Huffman tree (faster, lower compression).
    CPA_DC_HT_STATIC = 0,
    /// Dynamic Huffman tree (slower, better compression).
    CPA_DC_HT_FULL_DYNAMIC = 1,
}

/// Session direction for compression/decompression.
#[repr(C)]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CpaDcSessionDir {
    /// Compression only.
    CPA_DC_DIR_COMPRESS = 0,
    /// Decompression only.
    CPA_DC_DIR_DECOMPRESS = 1,
    /// Both compression and decompression.
    CPA_DC_DIR_COMBINED = 2,
}

/// Session state for compression/decompression.
#[repr(C)]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CpaDcSessionState {
    /// Stateful session (maintains history across requests).
    CPA_DC_STATEFUL = 0,
    /// Stateless session (each request is independent).
    CPA_DC_STATELESS = 1,
}

/// Flush flags for compression operations.
#[repr(C)]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CpaDcFlush {
    /// No flush - accumulate data.
    CPA_DC_FLUSH_NONE = 0,
    /// Final flush - end of stream.
    CPA_DC_FLUSH_FINAL = 1,
    /// Sync flush - flush to byte boundary.
    CPA_DC_FLUSH_SYNC = 2,
    /// Full flush - reset compression state.
    CPA_DC_FLUSH_FULL = 3,
}

/// Request type for multi-request operations.
#[repr(C)]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CpaDcReqType {
    /// First request in a sequence.
    CPA_DC_REQ_FIRST = 0,
    /// Subsequent request in a sequence.
    CPA_DC_REQ_SUBSEQUENT = 1,
}

/// Checksum type for data integrity verification.
#[repr(C)]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CpaDcChecksum {
    /// No checksum.
    CPA_DC_NONE = 0,
    /// CRC-32 checksum.
    CPA_DC_CRC32 = 1,
    /// Adler-32 checksum.
    CPA_DC_ADLER32 = 2,
    /// Both CRC-32 and Adler-32 checksums.
    CPA_DC_CRC32_ADLER32 = 3,
    /// XXHash-32 checksum.
    CPA_DC_XXHASH32 = 4,
}

/// Compression session setup data.
#[repr(C)]
#[derive(Debug, Clone, Copy)]
pub struct CpaDcSessionSetupData {
    /// Compression level (1-9).
    pub compLevel: CpaDcCompLvl,
    /// Compression algorithm.
    pub compType: CpaDcCompType,
    /// Huffman tree type.
    pub huffType: CpaDcHuffType,
    /// Auto-select best Huffman tree.
    pub autoSelectBestHuffmanTree: CpaBoolean,
    /// Session direction (compress/decompress).
    pub sessDirection: CpaDcSessionDir,
    /// Session state (stateful/stateless).
    pub sessState: CpaDcSessionState,
    /// Checksum type.
    pub checksum: CpaDcChecksum,
}

/// Compression operation data.
#[repr(C)]
#[derive(Debug, Clone, Copy)]
pub struct CpaDcOpData {
    /// Flush flag for output.
    pub flushFlag: CpaDcFlush,
    /// Compress and verify in single operation.
    pub compressAndVerify: CpaBoolean,
    /// Compress, verify, and recover on error.
    pub compressAndVerifyAndRecover: CpaBoolean,
    /// Enable integrity CRC check.
    pub integrityCrcCheck: CpaBoolean,
    /// Reserved field.
    pub reserved: u32,
    /// Skip data in input buffer.
    pub inputSkipData: CpaFlatBuffer,
    /// Skip data in output buffer.
    pub outputSkipData: CpaFlatBuffer,
}

/// Compression results.
#[repr(C)]
#[derive(Debug, Clone, Copy)]
pub struct CpaDcRqResults {
    /// Operation status.
    pub status: CpaStatus,
    /// Bytes consumed from input.
    pub consumed: u32,
    /// Bytes produced to output.
    pub produced: u32,
    /// CRC-32 checksum.
    pub crc32: u32,
    /// Adler-32 checksum.
    pub adler32: u32,
    /// Combined checksum (algorithm-dependent).
    pub checksum: u64,
}

/// DC instance capabilities.
#[repr(C)]
#[derive(Debug, Clone)]
pub struct CpaDcInstanceCapabilities {
    /// Supports compress-and-verify.
    pub compressAndVerify: CpaBoolean,
    /// Supports compress-verify-recover.
    pub compressAndVerifyAndRecover: CpaBoolean,
    /// Supports batch and pack operations.
    pub batchAndPack: CpaBoolean,
    /// Supports 64-bit integrity CRCs.
    pub integrityCrcs64b: CpaBoolean,
    /// Supports CRC-32 checksums.
    pub checksumCRC32: CpaBoolean,
    /// Supports CRC-64 checksums.
    pub checksumCRC64: CpaBoolean,
    /// Supports Adler-32 checksums.
    pub checksumAdler32: CpaBoolean,
    /// Supports XXHash-32 checksums.
    pub checksumXXHash32: CpaBoolean,
    /// Supports dynamic Huffman trees.
    pub dynamicHuffman: CpaBoolean,
    /// Supports precompiled Huffman trees.
    pub precompiledHuffman: CpaBoolean,
    /// Supports auto-selecting best Huffman tree.
    pub autoSelectBestHuffmanTree: CpaBoolean,
    /// Bitmap of valid window sizes.
    pub validWindowSizes: [CpaBoolean; 32],
}

/// Callback function type for DC operations
pub type CpaDcCallbackFn =
    Option<unsafe extern "C" fn(callbackTag: *mut c_void, status: CpaStatus)>;

// ═══════════════════════════════════════════════════════════════════════════════
// CY (CRYPTOGRAPHIC) TYPES
// ═══════════════════════════════════════════════════════════════════════════════

/// Symmetric session handle
pub type CpaCySymSessionCtx = *mut c_void;

/// Symmetric operation type.
#[repr(C)]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CpaCySymOp {
    /// Cipher operation only.
    CPA_CY_SYM_OP_CIPHER = 0,
    /// Hash operation only.
    CPA_CY_SYM_OP_HASH = 1,
    /// Algorithm chaining (cipher + hash).
    CPA_CY_SYM_OP_ALGORITHM_CHAINING = 2,
}

/// Symmetric cipher algorithm.
#[repr(C)]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CpaCySymCipherAlgorithm {
    /// No cipher (passthrough).
    CPA_CY_SYM_CIPHER_NULL = 0,
    /// ARC4 stream cipher (deprecated).
    CPA_CY_SYM_CIPHER_ARC4 = 1,
    /// AES in ECB mode.
    CPA_CY_SYM_CIPHER_AES_ECB = 2,
    /// AES in CBC mode.
    CPA_CY_SYM_CIPHER_AES_CBC = 3,
    /// AES in CTR mode.
    CPA_CY_SYM_CIPHER_AES_CTR = 4,
    /// AES-CCM authenticated encryption.
    CPA_CY_SYM_CIPHER_AES_CCM = 5,
    /// AES-GCM authenticated encryption.
    CPA_CY_SYM_CIPHER_AES_GCM = 6,
    /// AES-XTS for disk encryption.
    CPA_CY_SYM_CIPHER_AES_XTS = 7,
    /// ChaCha20 stream cipher.
    CPA_CY_SYM_CIPHER_CHACHA = 8,
    /// SM4 in ECB mode (Chinese standard).
    CPA_CY_SYM_CIPHER_SM4_ECB = 9,
    /// SM4 in CBC mode (Chinese standard).
    CPA_CY_SYM_CIPHER_SM4_CBC = 10,
    /// SM4 in CTR mode (Chinese standard).
    CPA_CY_SYM_CIPHER_SM4_CTR = 11,
}

/// Cipher direction for encryption/decryption.
#[repr(C)]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CpaCySymCipherDirection {
    /// Encrypt data.
    CPA_CY_SYM_CIPHER_DIRECTION_ENCRYPT = 0,
    /// Decrypt data.
    CPA_CY_SYM_CIPHER_DIRECTION_DECRYPT = 1,
}

/// Hash algorithm for integrity verification.
#[repr(C)]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CpaCySymHashAlgorithm {
    /// No hash.
    CPA_CY_SYM_HASH_NONE = 0,
    /// MD5 (deprecated, insecure).
    CPA_CY_SYM_HASH_MD5 = 1,
    /// SHA-1 (deprecated, insecure).
    CPA_CY_SYM_HASH_SHA1 = 2,
    /// SHA-224.
    CPA_CY_SYM_HASH_SHA224 = 3,
    /// SHA-256.
    CPA_CY_SYM_HASH_SHA256 = 4,
    /// SHA-384.
    CPA_CY_SYM_HASH_SHA384 = 5,
    /// SHA-512.
    CPA_CY_SYM_HASH_SHA512 = 6,
    /// AES-XCBC MAC.
    CPA_CY_SYM_HASH_AES_XCBC = 7,
    /// AES-CCM authentication.
    CPA_CY_SYM_HASH_AES_CCM = 8,
    /// AES-GCM authentication (GHASH).
    CPA_CY_SYM_HASH_AES_GCM = 9,
    /// AES-CMAC.
    CPA_CY_SYM_HASH_AES_CMAC = 10,
    /// AES-GMAC.
    CPA_CY_SYM_HASH_AES_GMAC = 11,
    /// Poly1305.
    CPA_CY_SYM_HASH_POLY = 12,
    /// SM3 (Chinese standard).
    CPA_CY_SYM_HASH_SM3 = 13,
    /// SHA3-256.
    CPA_CY_SYM_HASH_SHA3_256 = 14,
    /// SHA3-384.
    CPA_CY_SYM_HASH_SHA3_384 = 15,
    /// SHA3-512.
    CPA_CY_SYM_HASH_SHA3_512 = 16,
}

/// Hash mode for symmetric operations.
#[repr(C)]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CpaCySymHashMode {
    /// Plain hash (no key).
    CPA_CY_SYM_HASH_MODE_PLAIN = 0,
    /// Authentication mode (keyed MAC).
    CPA_CY_SYM_HASH_MODE_AUTH = 1,
    /// Nested hash (HMAC).
    CPA_CY_SYM_HASH_MODE_NESTED = 2,
}

/// Cipher setup data for symmetric crypto.
#[repr(C)]
#[derive(Debug, Clone, Copy)]
pub struct CpaCySymCipherSetupData {
    /// Cipher algorithm.
    pub cipherAlgorithm: CpaCySymCipherAlgorithm,
    /// Key length in bytes.
    pub cipherKeyLenInBytes: u32,
    /// Pointer to cipher key.
    pub pCipherKey: *const u8,
    /// Encrypt or decrypt direction.
    pub cipherDirection: CpaCySymCipherDirection,
}

/// Hash setup data for symmetric crypto.
#[repr(C)]
#[derive(Debug, Clone, Copy)]
pub struct CpaCySymHashSetupData {
    /// Hash algorithm.
    pub hashAlgorithm: CpaCySymHashAlgorithm,
    /// Hash mode (plain/auth/nested).
    pub hashMode: CpaCySymHashMode,
    /// Digest result length in bytes.
    pub digestResultLenInBytes: u32,
    /// Authentication mode setup data.
    pub authModeSetupData: CpaCySymHashAuthModeSetupData,
}

/// Authentication mode setup data.
#[repr(C)]
#[derive(Debug, Clone, Copy)]
pub struct CpaCySymHashAuthModeSetupData {
    /// Pointer to authentication key.
    pub authKey: *const u8,
    /// Authentication key length in bytes.
    pub authKeyLenInBytes: u32,
    /// Additional authenticated data length.
    pub aadLenInBytes: u32,
}

/// Symmetric session setup data.
#[repr(C)]
#[derive(Debug, Clone, Copy)]
pub struct CpaCySymSessionSetupData {
    /// Session priority.
    pub sessionPriority: u32,
    /// Symmetric operation type.
    pub symOperation: CpaCySymOp,
    /// Cipher setup data.
    pub cipherSetupData: CpaCySymCipherSetupData,
    /// Hash setup data.
    pub hashSetupData: CpaCySymHashSetupData,
    /// Algorithm chaining order.
    pub algChainOrder: u32,
    /// Digest is appended to data.
    pub digestIsAppended: CpaBoolean,
    /// Verify digest on decryption.
    pub verifyDigest: CpaBoolean,
    /// Partial packets not required.
    pub partialsNotRequired: CpaBoolean,
}

/// Symmetric operation data.
#[repr(C)]
#[derive(Debug, Clone, Copy)]
pub struct CpaCySymOpData {
    /// Session context.
    pub sessionCtx: CpaCySymSessionCtx,
    /// Packet type.
    pub packetType: u32,
    /// Pointer to initialization vector.
    pub pIv: *const u8,
    /// IV length in bytes.
    pub ivLenInBytes: u32,
    /// Crypto start offset in source buffer.
    pub cryptoStartSrcOffsetInBytes: u32,
    /// Message length to cipher in bytes.
    pub messageLenToCipherInBytes: u32,
    /// Hash start offset in source buffer.
    pub hashStartSrcOffsetInBytes: u32,
    /// Message length to hash in bytes.
    pub messageLenToHashInBytes: u32,
    /// Pointer to digest result buffer.
    pub pDigestResult: *mut u8,
    /// Pointer to additional authenticated data.
    pub pAdditionalAuthData: *const u8,
}

/// Callback function type for symmetric crypto operations
pub type CpaCySymCbFunc = Option<
    unsafe extern "C" fn(
        callbackTag: *mut c_void,
        status: CpaStatus,
        operationType: CpaCySymOp,
        pOpData: *mut c_void,
        pDstBuffer: *mut CpaBufferList,
        verifyResult: CpaBoolean,
    ),
>;

// ═══════════════════════════════════════════════════════════════════════════════
// SAL (SERVICE ACCESS LAYER) FUNCTIONS
// ═══════════════════════════════════════════════════════════════════════════════

// SAFETY INVARIANTS:
// 1. These are Intel QuickAssist Technology (QAT) API declarations (libqat.so)
// 2. icp_sal_userStartMultiProcess must be called before any other QAT function
// 3. All CpaInstanceHandle values must be obtained from cpaDcGetInstances/cpaCyGetInstances
// 4. All CpaBufferList structures must contain valid, DMA-able memory from qaeMemAllocNUMA
// 5. Session handles must be initialized via cpaDcInitSession/cpaCySymInitSession
// 6. Callback functions must remain valid for the lifetime of async operations
// 7. All instances must be stopped via cpaDcStopInstance before shutdown
//
// JUSTIFICATION:
// Intel QAT provides hardware-accelerated compression (DEFLATE, LZ4, ZSTD) and
// cryptography (AES-GCM) with 10-50x speedup over software implementations.
// These declarations match Intel's cpa.h and cpa_dc.h headers exactly.
#[cfg(feature = "qat")]
unsafe extern "C" {
    /// Initialize QAT for multi-process mode
    ///
    /// # Arguments
    /// * `pProcessName` - Process name for identification (e.g., "SSL", "LCPFS")
    /// * `limitDevAccess` - CPA_TRUE to limit device access, CPA_FALSE for full access
    ///
    /// # Returns
    /// * CPA_STATUS_SUCCESS on success
    /// * CPA_STATUS_FAIL if initialization failed
    pub fn icp_sal_userStartMultiProcess(
        pProcessName: *const c_char,
        limitDevAccess: CpaBoolean,
    ) -> CpaStatus;

    /// Stop QAT userspace
    pub fn icp_sal_userStop() -> CpaStatus;

    /// Check if QAT is running
    pub fn icp_sal_userIsQatRunning() -> CpaBoolean;
}

// ═══════════════════════════════════════════════════════════════════════════════
// DC (COMPRESSION) INSTANCE FUNCTIONS
// ═══════════════════════════════════════════════════════════════════════════════

// SAFETY INVARIANTS:
// See SAL FUNCTIONS block above - same invariants apply.
// Additionally:
// 1. Instance handles from cpaDcGetInstances are only valid after cpaDcStartInstance
// 2. Session setup requires valid CpaDcSessionSetupData with supported algorithms
// 3. Compression buffers must be sized according to cpaDcGetCompressBound
#[cfg(feature = "qat")]
unsafe extern "C" {
    /// Get number of DC instances
    pub fn cpaDcGetNumInstances(pNumInstances: *mut u16) -> CpaStatus;

    /// Get DC instances
    pub fn cpaDcGetInstances(numInstances: u16, pInstances: *mut CpaInstanceHandle) -> CpaStatus;

    /// Start DC instance
    pub fn cpaDcStartInstance(
        instanceHandle: CpaInstanceHandle,
        numConcurrentRequests: u16,
    ) -> CpaStatus;

    /// Stop DC instance
    pub fn cpaDcStopInstance(instanceHandle: CpaInstanceHandle) -> CpaStatus;

    /// Query DC instance capabilities
    pub fn cpaDcQueryCapabilities(
        instanceHandle: CpaInstanceHandle,
        pInstanceCapabilities: *mut CpaDcInstanceCapabilities,
    ) -> CpaStatus;

    /// Get session size
    pub fn cpaDcGetSessionSize(
        instanceHandle: CpaInstanceHandle,
        pSessionSetupData: *const CpaDcSessionSetupData,
        pSessionSize: *mut u32,
        pContextSize: *mut u32,
    ) -> CpaStatus;

    /// Initialize session
    pub fn cpaDcInitSession(
        instanceHandle: CpaInstanceHandle,
        pSessionHandle: CpaDcSessionHandle,
        pSessionSetupData: *const CpaDcSessionSetupData,
        pContextBuffer: *mut c_void,
        dcCbFunc: CpaDcCallbackFn,
    ) -> CpaStatus;

    /// Remove session
    pub fn cpaDcRemoveSession(
        instanceHandle: CpaInstanceHandle,
        pSessionHandle: CpaDcSessionHandle,
    ) -> CpaStatus;

    /// Compress data (synchronous)
    pub fn cpaDcCompressData(
        instanceHandle: CpaInstanceHandle,
        pSessionHandle: CpaDcSessionHandle,
        pSrcBuff: *const CpaBufferList,
        pDestBuff: *mut CpaBufferList,
        pResults: *mut CpaDcRqResults,
        flushFlag: CpaDcFlush,
        callbackTag: *mut c_void,
    ) -> CpaStatus;

    /// Compress data v2 (with more options)
    pub fn cpaDcCompressData2(
        instanceHandle: CpaInstanceHandle,
        pSessionHandle: CpaDcSessionHandle,
        pSrcBuff: *const CpaBufferList,
        pDestBuff: *mut CpaBufferList,
        pOpData: *const CpaDcOpData,
        pResults: *mut CpaDcRqResults,
        callbackTag: *mut c_void,
    ) -> CpaStatus;

    /// Decompress data
    pub fn cpaDcDecompressData(
        instanceHandle: CpaInstanceHandle,
        pSessionHandle: CpaDcSessionHandle,
        pSrcBuff: *const CpaBufferList,
        pDestBuff: *mut CpaBufferList,
        pResults: *mut CpaDcRqResults,
        flushFlag: CpaDcFlush,
        callbackTag: *mut c_void,
    ) -> CpaStatus;

    /// Decompress data v2
    pub fn cpaDcDecompressData2(
        instanceHandle: CpaInstanceHandle,
        pSessionHandle: CpaDcSessionHandle,
        pSrcBuff: *const CpaBufferList,
        pDestBuff: *mut CpaBufferList,
        pOpData: *const CpaDcOpData,
        pResults: *mut CpaDcRqResults,
        callbackTag: *mut c_void,
    ) -> CpaStatus;

    /// Poll for DC responses
    pub fn icp_sal_DcPollInstance(
        instanceHandle: CpaInstanceHandle,
        response_quota: u32,
    ) -> CpaStatus;
}

// ═══════════════════════════════════════════════════════════════════════════════
// CY (CRYPTO) INSTANCE FUNCTIONS
// ═══════════════════════════════════════════════════════════════════════════════

// SAFETY INVARIANTS:
// See SAL FUNCTIONS block above - same invariants apply.
// Additionally:
// 1. Crypto sessions require valid CpaCySymSessionSetupData with key material
// 2. Key material must remain valid for session lifetime (copied internally)
// 3. IV/nonce buffers must be correctly sized for the algorithm (12 bytes for GCM)
// 4. AAD and tag buffers required for authenticated encryption modes
#[cfg(feature = "qat")]
unsafe extern "C" {
    /// Get number of crypto instances
    pub fn cpaCyGetNumInstances(pNumInstances: *mut u16) -> CpaStatus;

    /// Get crypto instances
    pub fn cpaCyGetInstances(numInstances: u16, pInstances: *mut CpaInstanceHandle) -> CpaStatus;

    /// Start crypto instance
    pub fn cpaCyStartInstance(instanceHandle: CpaInstanceHandle) -> CpaStatus;

    /// Stop crypto instance
    pub fn cpaCyStopInstance(instanceHandle: CpaInstanceHandle) -> CpaStatus;

    /// Get symmetric session size
    pub fn cpaCySymSessionCtxGetSize(
        instanceHandle: CpaInstanceHandle,
        pSessionSetupData: *const CpaCySymSessionSetupData,
        pSessionCtxSizeInBytes: *mut u32,
    ) -> CpaStatus;

    /// Initialize symmetric session
    pub fn cpaCySymInitSession(
        instanceHandle: CpaInstanceHandle,
        pSymCb: CpaCySymCbFunc,
        pSessionSetupData: *const CpaCySymSessionSetupData,
        sessionCtx: CpaCySymSessionCtx,
    ) -> CpaStatus;

    /// Remove symmetric session
    pub fn cpaCySymRemoveSession(
        instanceHandle: CpaInstanceHandle,
        pSessionCtx: CpaCySymSessionCtx,
    ) -> CpaStatus;

    /// Perform symmetric crypto operation
    pub fn cpaCySymPerformOp(
        instanceHandle: CpaInstanceHandle,
        callbackTag: *mut c_void,
        pOpData: *const CpaCySymOpData,
        pSrcBuffer: *const CpaBufferList,
        pDstBuffer: *mut CpaBufferList,
        pVerifyResult: *mut CpaBoolean,
    ) -> CpaStatus;

    /// Poll for crypto responses
    pub fn icp_sal_CyPollInstance(
        instanceHandle: CpaInstanceHandle,
        response_quota: u32,
    ) -> CpaStatus;
}

// ═══════════════════════════════════════════════════════════════════════════════
// QAE MEMORY FUNCTIONS (DMA-able memory allocation)
// ═══════════════════════════════════════════════════════════════════════════════

// SAFETY INVARIANTS:
// 1. Memory from qaeMemAllocNUMA is DMA-able and physically contiguous
// 2. Alignment must be a power of 2, typically 64 for cache-line alignment
// 3. NUMA node must be valid (0 to system max, or -1 for any node)
// 4. qaeMemFreeNUMA takes pointer-to-pointer and sets it to NULL after free
// 5. All QAT buffer data must use this allocator, not regular malloc/alloc
//
// JUSTIFICATION:
// QAT hardware requires physically contiguous, DMA-able memory for zero-copy
// transfers between CPU and accelerator. Standard allocators don't guarantee this.
#[cfg(feature = "qat")]
unsafe extern "C" {
    /// Allocate NUMA-aware, DMA-able memory
    ///
    /// # Arguments
    /// * `size` - Size in bytes
    /// * `node` - NUMA node ID
    /// * `alignment` - Memory alignment
    ///
    /// # Returns
    /// Pointer to allocated memory, or NULL on failure
    pub fn qaeMemAllocNUMA(size: usize, node: c_int, alignment: usize) -> *mut c_void;

    /// Free NUMA memory
    pub fn qaeMemFreeNUMA(ptr: *mut *mut c_void);

    /// Allocate physically contiguous memory
    pub fn qaeMemAlloc(size: usize) -> *mut c_void;

    /// Free physically contiguous memory
    pub fn qaeMemFree(ptr: *mut *mut c_void);

    /// Convert virtual address to physical address
    pub fn qaeVirtToPhysNUMA(pVirtAddr: *mut c_void) -> CpaPhysicalAddr;
}

// ═══════════════════════════════════════════════════════════════════════════════
// SAFE WRAPPER TYPES
// ═══════════════════════════════════════════════════════════════════════════════

/// Safe wrapper for QAT instance handles
#[derive(Debug)]
pub struct QatInstance {
    handle: CpaInstanceHandle,
    is_dc: bool,
}

impl QatInstance {
    /// Create a new DC (compression) instance wrapper
    ///
    /// # Safety
    ///
    /// SAFETY INVARIANTS:
    /// - `handle` must be a non-null pointer to a valid QAT DC instance
    /// - The instance must have been started via `cpaDcStartInstance`
    /// - The instance must not be stopped or freed while this wrapper exists
    pub unsafe fn new_dc(handle: CpaInstanceHandle) -> Self {
        Self {
            handle,
            is_dc: true,
        }
    }

    /// Create a new CY (crypto) instance wrapper
    ///
    /// # Safety
    ///
    /// SAFETY INVARIANTS:
    /// - `handle` must be a non-null pointer to a valid QAT CY instance
    /// - The instance must have been started via `cpaCyStartInstance`
    /// - The instance must not be stopped or freed while this wrapper exists
    pub unsafe fn new_cy(handle: CpaInstanceHandle) -> Self {
        Self {
            handle,
            is_dc: false,
        }
    }

    /// Get raw handle
    pub fn handle(&self) -> CpaInstanceHandle {
        self.handle
    }

    /// Check if this is a DC instance
    pub fn is_dc(&self) -> bool {
        self.is_dc
    }
}

/// DMA-able buffer wrapper
#[cfg(feature = "qat")]
pub struct QatBuffer {
    ptr: *mut u8,
    size: usize,
    node: i32,
}

#[cfg(feature = "qat")]
impl QatBuffer {
    /// Allocate a new QAT buffer
    pub fn new(size: usize, node: i32) -> Option<Self> {
        let ptr = unsafe { qaeMemAllocNUMA(size, node, 64) as *mut u8 };
        if ptr.is_null() {
            None
        } else {
            Some(Self { ptr, size, node })
        }
    }

    /// Get pointer to buffer data
    pub fn as_ptr(&self) -> *mut u8 {
        self.ptr
    }

    /// Get buffer size
    pub fn size(&self) -> usize {
        self.size
    }

    /// Get physical address for DMA
    pub fn phys_addr(&self) -> CpaPhysicalAddr {
        unsafe { qaeVirtToPhysNUMA(self.ptr as *mut c_void) }
    }

    /// Copy data into buffer
    ///
    /// # Safety
    ///
    /// SAFETY INVARIANTS:
    /// - `data.len()` must not exceed `self.size`
    /// - The buffer must have been successfully allocated (not null)
    /// - No concurrent access to the buffer memory region
    pub unsafe fn copy_from(&mut self, data: &[u8]) {
        debug_assert!(data.len() <= self.size);
        // SAFETY: Caller guarantees data.len() <= self.size and buffer is valid
        unsafe {
            core::ptr::copy_nonoverlapping(data.as_ptr(), self.ptr, data.len());
        }
    }

    /// Copy data out of buffer
    ///
    /// # Safety
    ///
    /// SAFETY INVARIANTS:
    /// - `len` must not exceed `self.size`
    /// - `len` must not exceed `dest.len()`
    /// - The buffer must have been successfully allocated (not null)
    /// - No concurrent writes to the buffer memory region
    pub unsafe fn copy_to(&self, dest: &mut [u8], len: usize) {
        debug_assert!(len <= self.size);
        debug_assert!(len <= dest.len());
        // SAFETY: Caller guarantees bounds and buffer validity
        unsafe {
            core::ptr::copy_nonoverlapping(self.ptr, dest.as_mut_ptr(), len);
        }
    }
}

#[cfg(feature = "qat")]
impl Drop for QatBuffer {
    fn drop(&mut self) {
        unsafe {
            let mut ptr = self.ptr as *mut c_void;
            qaeMemFreeNUMA(&mut ptr);
        }
    }
}

// ═══════════════════════════════════════════════════════════════════════════════
// ERROR TYPES
// ═══════════════════════════════════════════════════════════════════════════════

/// QAT error type
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum QatFfiError {
    /// Initialization failed
    InitFailed,
    /// No instances available
    NoInstances,
    /// Instance start failed
    StartFailed,
    /// Session creation failed
    SessionFailed,
    /// Memory allocation failed
    MemoryError,
    /// Operation failed
    OperationFailed(CpaStatus),
    /// QAT not running
    NotRunning,
    /// Invalid parameter
    InvalidParam,
    /// Resource unavailable
    ResourceBusy,
}

impl QatFfiError {
    /// Convert CPA status to error
    pub fn from_status(status: CpaStatus) -> Result<(), Self> {
        match status {
            CPA_STATUS_SUCCESS => Ok(()),
            CPA_STATUS_FAIL => Err(QatFfiError::OperationFailed(status)),
            CPA_STATUS_RETRY => Err(QatFfiError::ResourceBusy),
            CPA_STATUS_RESOURCE => Err(QatFfiError::ResourceBusy),
            CPA_STATUS_INVALID_PARAM => Err(QatFfiError::InvalidParam),
            CPA_STATUS_FATAL => Err(QatFfiError::OperationFailed(status)),
            CPA_STATUS_UNSUPPORTED => Err(QatFfiError::OperationFailed(status)),
            _ => Err(QatFfiError::OperationFailed(status)),
        }
    }
}

// ═══════════════════════════════════════════════════════════════════════════════
// TESTS
// ═══════════════════════════════════════════════════════════════════════════════

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_cpa_status_constants() {
        assert_eq!(CPA_STATUS_SUCCESS, 0);
        assert_eq!(CPA_STATUS_FAIL, -1);
        assert_eq!(CPA_STATUS_RETRY, 1);
    }

    #[test]
    fn test_cpa_boolean_constants() {
        assert_eq!(CPA_FALSE, 0);
        assert_eq!(CPA_TRUE, 1);
    }

    #[test]
    fn test_flat_buffer_size() {
        assert_eq!(
            core::mem::size_of::<CpaFlatBuffer>(),
            core::mem::size_of::<u32>() + core::mem::size_of::<*mut u8>()
        );
    }

    #[test]
    fn test_compression_levels() {
        assert_eq!(CpaDcCompLvl::CPA_DC_L1 as i32, 1);
        assert_eq!(CpaDcCompLvl::CPA_DC_L9 as i32, 9);
    }

    #[test]
    fn test_cipher_algorithms() {
        assert_eq!(CpaCySymCipherAlgorithm::CPA_CY_SYM_CIPHER_AES_GCM as i32, 6);
        assert_eq!(CpaCySymCipherAlgorithm::CPA_CY_SYM_CIPHER_AES_XTS as i32, 7);
        assert_eq!(CpaCySymCipherAlgorithm::CPA_CY_SYM_CIPHER_CHACHA as i32, 8);
    }

    #[test]
    fn test_hash_algorithms() {
        assert_eq!(CpaCySymHashAlgorithm::CPA_CY_SYM_HASH_SHA256 as i32, 4);
        assert_eq!(CpaCySymHashAlgorithm::CPA_CY_SYM_HASH_AES_GCM as i32, 9);
    }

    #[test]
    fn test_error_conversion() {
        assert!(QatFfiError::from_status(CPA_STATUS_SUCCESS).is_ok());
        assert!(matches!(
            QatFfiError::from_status(CPA_STATUS_FAIL),
            Err(QatFfiError::OperationFailed(_))
        ));
        assert!(matches!(
            QatFfiError::from_status(CPA_STATUS_RETRY),
            Err(QatFfiError::ResourceBusy)
        ));
    }

    #[test]
    fn test_compression_types() {
        assert_eq!(CpaDcCompType::CPA_DC_DEFLATE as i32, 0);
        assert_eq!(CpaDcCompType::CPA_DC_LZ4 as i32, 1);
        assert_eq!(CpaDcCompType::CPA_DC_ZSTD as i32, 3);
    }
}