// Public nt-lite kernel-audio provider declarations.

#pragma once

#include <stddef.h>
#include <stdint.h>
#include <ntlite/status.h>

struct DEVICE_OBJECT;
typedef struct IO_AUDIO_ENDPOINT IO_AUDIO_ENDPOINT;

// Identifies one logical render destination rather than one codec pin.
typedef enum IO_AUDIO_ENDPOINT_KIND {
    IoAudioEndpointLineOut = 1,
    IoAudioEndpointSpeakerHeadphone,
    IoAudioEndpointOtherAnalog
} IO_AUDIO_ENDPOINT_KIND;

// Identifies the canonical interleaved PCM sample representation.
typedef enum IO_AUDIO_SAMPLE_FORMAT {
    IoAudioSampleS16 = 1
} IO_AUDIO_SAMPLE_FORMAT;

// Describes interleaved PCM frames.
typedef struct IO_AUDIO_FORMAT {
    uint32_t SampleRate;
    uint16_t ChannelCount;
    uint16_t SampleFormat;
} IO_AUDIO_FORMAT;

#define IO_AUDIO_ENDPOINT_CAP_JACK_SENSE     0x00000001u
#define IO_AUDIO_ENDPOINT_CAP_HARDWARE_GAIN  0x00000002u
#define IO_AUDIO_ENDPOINT_CAP_VALID_MASK     0x00000003u

// Bounds provider-advertised hardware gain ranges in millidecibels.
#define IO_AUDIO_HARDWARE_GAIN_LIMIT_MILLIDB 200000

// Distinguishes orderly teardown from surprise removal where registers may no longer be accessible.
typedef enum IO_AUDIO_REMOVAL_MODE {
    IoAudioOrderlyRemoval = 1,
    IoAudioSurpriseRemoval
} IO_AUDIO_REMOVAL_MODE;

#define IO_AUDIO_FAILURE_HARDWARE_INACCESSIBLE 0x00000001u
#define IO_AUDIO_FAILURE_VALID_MASK             0x00000001u

// Provider operations are invoked only at PASSIVE_LEVEL by the endpoint mixer thread.
typedef struct IO_AUDIO_PROVIDER_OPERATIONS {
    // Starts DMA only after the ring contains at least two prepared periods.
    // Failure must leave the provider stopped; Stop may still be called for partial-start cleanup.
    KSTATUS (*Start)(void* providerContext);
    // Stops DMA before unregister permits provider storage to be released.
    void (*Stop)(void* providerContext);
    // Applies endpoint gain and mute only with IO_AUDIO_ENDPOINT_CAP_HARDWARE_GAIN.
    KSTATUS (*SetGain)(void* providerContext, int32_t gainMilliDb, uint8_t muted);
} IO_AUDIO_PROVIDER_OPERATIONS;

// Registers one fixed-format render ring owned by a hardware provider.
// The provider must keep DMA stopped and the physical output muted until Start is called.
typedef struct IO_AUDIO_ENDPOINT_REGISTRATION {
    struct DEVICE_OBJECT* Device;
    IO_AUDIO_ENDPOINT_KIND Kind;
    uint32_t Capabilities;
    uint8_t InitiallyAvailable;
    void* ProviderContext;
    IO_AUDIO_PROVIDER_OPERATIONS Operations;
    void* PeriodBuffer;
    size_t PeriodBufferBytes;
    uint32_t PeriodCount;
    uint32_t FramesPerPeriod;
    size_t PeriodStrideBytes;
    IO_AUDIO_FORMAT HardwareFormat;
    // Gain fields must be zero unless IO_AUDIO_ENDPOINT_CAP_HARDWARE_GAIN is present.
    int32_t HardwareGainMinimumMilliDb;
    int32_t HardwareGainMaximumMilliDb;
    uint32_t HardwareGainStepMilliDb;
} IO_AUDIO_ENDPOINT_REGISTRATION;

// Driver-visible services for registering and advancing kernel audio endpoints.
typedef struct NTL_DDK_AUDIO {
    // Registers one endpoint and returns a provider-owned reference valid until unregister returns.
    KSTATUS (*RegisterEndpoint)(const IO_AUDIO_ENDPOINT_REGISTRATION* registration,
                                IO_AUDIO_ENDPOINT** outEndpoint);

    // Stops the endpoint, removes it from enumeration, and consumes the provider-owned reference.
    void (*UnregisterEndpoint)(IO_AUDIO_ENDPOINT* endpoint, IO_AUDIO_REMOVAL_MODE mode);

    // Reports one completed hardware period from ISR/DPC completion processing.
    // presentedFrames, hardwarePositionFrames, and interruptCount must be monotonic for the
    // endpoint lifetime. timestampTicks uses the DDK monotonic microsecond source.
    void (*NotifyPeriod)(IO_AUDIO_ENDPOINT* endpoint,
                         uint32_t completedPeriodIndex,
                         uint64_t presentedFrames,
                         uint64_t hardwarePositionFrames,
                         uint64_t interruptCount,
                         uint64_t timestampTicks);

    // Updates jack-derived endpoint availability without changing endpoint identity.
    void (*SetEndpointAvailable)(IO_AUDIO_ENDPOINT* endpoint, uint8_t available);

    // Fails an endpoint and wakes every stream owner.
    void (*ReportEndpointFailure)(IO_AUDIO_ENDPOINT* endpoint,
                                  KSTATUS status,
                                  uint32_t flags);
} NTL_DDK_AUDIO;