C++ tablet drivers optimization DOC (RU).md

Архитектура и правила оптимизации user-space драйвера графического планшета для osu! на чистом C++

Версия 5.1 · Сентябрь 2026

Краткое описание

Документ описывает создание драйвера графического планшета на C++20/C++23 под Windows, обеспечивающего субмикросекундную внутреннюю задержку конвейера (< 30 мкс) и сквозную задержку ввода уровня физического предела оборудования. Архитектура исключает сборку мусора, маршалинг и динамические аллокации в цикле обработки. Чтение выполняется монопольно через Win32 HID/IOCP со сбросом очередей ядра, синхронизация потоков построена на 128-битных снимках без блокировок (Atomic Snapshot), а передача курсора в osu! осуществляется через сертифицированные виртуальные шины без включения опасного режима тестовой подписи.

Конвенция требований

В документе используются строгие категории предписаний:

• ДОЛЖНО — строго обязательное инженерное требование. Нарушение приводит к нестабильности, задержкам или блокировкам античитами.
• СЛЕДУЕТ — рекомендация, необходимая для достижения наилучшей производительности.
• МОЖЕТ — допустимое решение, зависящее от конкретной аппаратной конфигурации.

0. Терминология, история версий и архитектурные решения

0.1. Глоссарий

0.2. Журнал изменений

• Версия 5.1:
  • Методика сквозного измерения адаптирована под аппаратные стенды с фотодиодами и скоростную съёмку (убрана привязка к NVIDIA Reflex Analyzer).
  • Добавлен разбор дескрипторов устройств основных производителей (Wacom, Huion, XP-Pen).
  • Описан механизм сброса очереди драйвера ядра (ring-drain fallback) при отказе API усечения буферов.
  • Реализован расчет экранных координат с учетом виртуального рабочего стола нескольких мониторов и разнородного DPI.
  • Внедрена горячая перезагрузка конфигурации без мьютексов.
• Версия 5.0:
  • Переход на непрерывную rate-independent адаптацию фильтра 1-Euro.
  • Интеграция с API управления профилями энергопотребления Windows 11 EcoQoS.
  • Использование 128-битного Atomic Snapshot на базе стандарта C++20.

0.3. Архитектурные решения

• [ADR-1] Эксклюзивный Win32 HID API с минимизацией буфера ядра: Открытие устройства с параметром dwShareMode = 0 (монопольный доступ) и сокращение очереди входящих пакетов (HidD_SetNumInputBuffers = 2). Исключает накопление задержки в буферах ядра и предотвращает параллельный перехват устройства клиентом osu!lazer.
• [ADR-2] Инъекция через сертифицированные виртуальные шины: Отказ от требования включения режима testsigning. Передача отчетов идет через доверенные драйверы (VTD / Nefarius VHID), что гарантирует работу античитов и сохранение сетевых функций osu!.
• [ADR-3] Приоритет абсолютной свежести данных: В ритм-играх устаревшие координаты теряют смысл. Очереди отбрасываются: потребитель всегда получает самый свежий отчет пера через 128-битный атомарный снимок std::atomic.
• [ADR-4] Вычисление DSP в пространстве координат сенсора: Фильтрация шумов выполняется до трансформации в экранные координаты, что обеспечивает одинаковый отклик независимо от размера активной зоны.
• [ADR-5] Запрет динамических аллокаций в горячем цикле: Любые вызовы malloc, new, изменения размеров контейнеров и захваты в лямбдах внутри цикла обработки ввода строго запрещены.

1. Архитектурная схема пайплайна

graph TD
    A[Планшет] -->|USB Interrupt Transfer| B[USB Root Hub контроллера]
    B -->|Аппаратный ISR/DPC| C[Стек ядра Windows HID]
    C -->|dwShareMode=0, NumBuffers=2| D[Очередь завершения IOCP]
    
    subgraph Горячий цикл ввода [Поток 1: P-Core, MMCSS Pro Audio]
        D -->|GetQueuedCompletionStatusEx| E[Разбор отчета вендора memcpy]
        E -->|Отсев битых пакетов| F[Нормализация X, Y, Pressure]
        F -->|memory_order_release| G[Атомарная запись 128-bit]
    end

    subgraph Обработка и инъекция [Поток 2: P-Core, MMCSS Pro Audio]
        G -->|memory_order_acquire| H[Атомарное чтение 128-bit]
        H -->|Адаптация по dt| I[Фильтр 1-Euro]
        I -->|Branchless FMA расчет| J[Координаты Virtual Desktop]
        J -->|IOCTL / Ring Buffer| K[Подписанный драйвер VTD/VHID]
    end

    K -->|WM_INPUT| L[osu! stable]
    K -->|SDL3 Pointer Subsystem| M[osu! lazer]

    subgraph Служебный поток [Watchdog / UI]
        N[Горячая перезагрузка конфига] -.->|memory_order_release| I
        N -.->|memory_order_release| J
    end

Loading

2. Цели и эталонные метрики

2.1. Ключевые метрики

Квантильный анализ: Среднее значение ($\mu$) скрывает микростаттеры. Главной метрикой стабильности служит значение p99.9: отклонение между медианой (p50) и 99.9-м процентилем не ДОЛЖНО превышать 20 мкс.

2.2. Эталонные замеры (Сравнение архитектур)

3. Подсистема ввода-вывода

3.1. Инициализация и стратегия обработки очереди ядра

Стандартный драйвер hidclass.sys по умолчанию резервирует буфер на 32 пакета. При задержке потока планировщиком очередь заполняется, приводя к чтению устаревших координат с задержкой в десятки миллисекунд.

Разработчик ДОЛЖЕН запросить эксклюзивный доступ и сократить системную очередь до двух отчетов:

#include 
#include 
#pragma comment(lib, "hid.lib")

HANDLE OpenTabletDevice(const wchar_t* devicePath, bool& outReducedBufferSupport) noexcept {
    HANDLE hDevice = CreateFileW(
        devicePath,
        GENERIC_READ | GENERIC_WRITE,
        0, // ДОЛЖНО: dwShareMode = 0 блокирует параллельные перехваты osu!lazer и OEM-утилит
        nullptr,
        OPEN_EXISTING,
        FILE_FLAG_OVERLAPPED,
        nullptr
    );

    if (hDevice == INVALID_HANDLE_VALUE) {
        return INVALID_HANDLE_VALUE;
    }

    // Сокращаем системную очередь hidclass.sys
    if (!HidD_SetNumInputBuffers(hDevice, 2)) {
        // Fallback: драйвер интерфейса не поддерживает вызов.
        // Будет задействован алгоритм сброса очереди (ring-drain loop).
        outReducedBufferSupport = false;
    } else {
        outReducedBufferSupport = true;
    }

    return hDevice;
}

Стратегия Fallback: Если outReducedBufferSupport == false, поток ввода ДОЛЖЕН вызывать GetQueuedCompletionStatusEx пакетами по 8–16 штук и передавать в конвейер исключительно последний корректный отчет из партии, мгновенно отбрасывая промежуточные.

3.2. Парсинг отчетов различных производителей

Разные производители используют собственные структуры размещения данных в пакетах:

enum class TabletVendor {
    Wacom,
    Huion,
    XPPen,
    GenericHid
};

struct VendorQuirks {
    TabletVendor vendor;
    uint8_t report_id;
    uint8_t byte_offset_x;
    uint8_t byte_offset_y;
    uint8_t byte_offset_pressure;
    float   max_raw_x;
    float   max_raw_y;
    float   max_raw_pressure;
};

// Извлечение данных без динамических аллокаций и без нарушения правил алиасинга
inline bool ParseVendorReport(
    const uint8_t* buffer, 
    size_t size, 
    const VendorQuirks& quirks, 
    TabletRawReport& outReport
) noexcept {
    if (size < 10 || buffer[0] != quirks.report_id) [[unlikely]] {
        return false;
    }

    uint16_t raw_x = 0, raw_y = 0, raw_press = 0;
    std::memcpy(&raw_x, buffer + quirks.byte_offset_x, sizeof(uint16_t));
    std::memcpy(&raw_y, buffer + quirks.byte_offset_y, sizeof(uint16_t));
    std::memcpy(&raw_press, buffer + quirks.byte_offset_pressure, sizeof(uint16_t));

    outReport.norm_x = static_cast(raw_x) / quirks.max_raw_x;
    outReport.norm_y = static_cast(raw_y) / quirks.max_raw_y;
    outReport.norm_pressure = static_cast(raw_press) / quirks.max_raw_pressure;
    outReport.buttons = buffer[1];
    return true;
}

4. Модель потоков, синхронизация и шедулинг

4.1. Межпоточный обмен через 128-битный Atomic Snapshot

Для устранения очередей и исключения чтения поврежденных данных обмен между потоком чтения и потоком инъекции ДОЛЖЕН выполняться через 16-байтную неделимую структуру:

#include 
#include 

struct alignas(16) TabletSnapshot {
    float    norm_x;        // 4 байта
    float    norm_y;        // 4 байта
    uint16_t pressure;      // 2 байта
    uint8_t  buttons;       // 1 байт
    uint8_t  pad;           // 1 байт
    uint32_t qpc_delta_us;  // 4 байта
};

static_assert(sizeof(TabletSnapshot) == 16, "Размер TabletSnapshot обязан составлять ровно 128 бит");
static_assert(std::atomic::is_always_lock_free, "Платформа обязана поддерживать 128-битные lock-free атомики");

class TabletStateChannel {
public:
    void Publish(const TabletSnapshot& snapshot) noexcept {
        m_state.store(snapshot, std::memory_order_release);
    }

    TabletSnapshot Consume() noexcept {
        return m_state.load(std::memory_order_acquire);
    }

private:
    alignas(64) std::atomic m_state{};
};

4.2. Управление шедулингом (MMCSS и отключение EcoQoS)

Потоки обработки ДОЛЖНЫ быть защищены от троттлинга частоты со стороны Windows 11:

#include 
#include 
#pragma comment(lib, "avrt.lib")

void OptimizeCurrentThreadScheduler() noexcept {
    // 1. Отключение энергосберегающего замедления Windows 11 (EcoQoS)
    THREAD_POWER_THROTTLING_STATE powerThrottling{};
    powerThrottling.Version = THREAD_POWER_THROTTLING_CURRENT_VERSION;
    powerThrottling.ControlMask = THREAD_POWER_THROTTLING_EXECUTION_SPEED;
    powerThrottling.StateMask = 0;

    SetThreadInformation(
        GetCurrentThread(),
        ThreadPowerThrottling,
        &powerThrottling,
        sizeof(powerThrottling)
    );

    // 2. Регистрация в подсистеме MMCSS (приоритет диапазона 26-27)
    DWORD taskIndex = 0;
    HANDLE hTask = AvSetMmThreadCharacteristicsW(L"Pro Audio", &taskIndex);
    if (hTask) {
        AvSetMmThreadPriority(hTask, AVRT_PRIORITY_CRITICAL);
    }
}

4.3. Привязка к физическим ядрам процессора

• Intel (архитектуры Alder Lake, Raptor Lake, Arrow Lake): Потоки драйвера ДОЛЖНЫ привязываться строго к производительным ядрам (P-Cores), исключая Core 0 (занято прерываниями системных часов).
• AMD Ryzen X3D (серии 7000, 9000): Потоки ДОЛЖНЫ привязываться к первому кристаллу (CCD 0), оснащенному 3D V-Cache (ядра 0–15), для исключения задержек межъядерной шины.

5. Фильтрация сигнала и расчет экранных координат

5.1. Фильтр 1-Euro с непрерывной адаптацией

Параметры фильтрации ДОЛЖНЫ рассчитываться по непрерывной временной дельте ($dt$), предотвращая искажение траектории при нестабильной частоте опроса шины:

#include 
#include 

struct OneEuroConfig {
    float min_cutoff;
    float beta;
    float d_cutoff;
};

class LowPassFilter {
    float m_hat_prev{0.0f};
    bool  m_initialized{false};
public:
    float Filter(float val, float alpha) noexcept {
        if (!m_initialized) {
            m_hat_prev = val;
            m_initialized = true;
            return val;
        }
        m_hat_prev = alpha * val + (1.0f - alpha) * m_hat_prev;
        return m_hat_prev;
    }
    float GetLast() const noexcept { return m_hat_prev; }
};

class OneEuroFilter1D {
    LowPassFilter m_x_filt;
    LowPassFilter m_dx_filt;

    static float CalculateAlpha(float rate, float cutoff) noexcept {
        const float tau = 1.0f / (2.0f * 3.14159265f * cutoff);
        const float te = 1.0f / rate;
        return 1.0f / (1.0f + tau / te);
    }

public:
    float Apply(float val, float dt, const OneEuroConfig& cfg) noexcept {
        const float rate = 1.0f / dt;
        const float dx = m_x_filt.Filter(val, CalculateAlpha(rate, cfg.d_cutoff)) - m_x_filt.GetLast();
        const float edx = m_dx_filt.Filter(dx / dt, CalculateAlpha(rate, cfg.d_cutoff));
        const float cutoff = cfg.min_cutoff + cfg.beta * std::abs(edx);
        return m_x_filt.Filter(val, CalculateAlpha(rate, cutoff));
    }
};

5.2. Расчет координат для нескольких мониторов

Маппинг нормализованных координат сенсора в пространство виртуального экрана выполняется аппаратно через инструкцию FMA без условных ветвлений:

struct AreaMappingConfig {
    float scale_x, offset_x;
    float scale_y, offset_y;
    float virtual_screen_x, virtual_screen_y;
    float virtual_screen_w, virtual_screen_h;
};

inline void MapToVirtualDesktop(
    float norm_x, 
    float norm_y, 
    const AreaMappingConfig& cfg, 
    float& out_desktop_x, 
    float& out_desktop_y
) noexcept {
    // 1. Ограничение активной зоны сенсора
    const float clamped_x = std::clamp(norm_x, 0.0f, 1.0f);
    const float clamped_y = std::clamp(norm_y, 0.0f, 1.0f);

    // 2. Аппаратный FMA расчет без условных переходов
    const float target_norm_x = std::fma(clamped_x, cfg.scale_x, cfg.offset_x);
    const float target_norm_y = std::fma(clamped_y, cfg.scale_y, cfg.offset_y);

    // 3. Перевод в абсолютные координаты виртуального экрана Windows (SM_CXVIRTUALSCREEN)
    out_desktop_x = cfg.virtual_screen_x + (target_norm_x * cfg.virtual_screen_w);
    out_desktop_y = cfg.virtual_screen_y + (target_norm_y * cfg.virtual_screen_h);
}

6. Конфигурация и горячая перезагрузка без блокировок

Для применения параметров рабочей зоны и фильтрации без перезапуска драйвера и без синхронизирующих примитивов используется атомарная подмена разделяемого указателя:

#include 

struct DriverRuntimeConfig {
    OneEuroConfig     filter_cfg;
    AreaMappingConfig mapping_cfg;
};

class ConfigManager {
public:
    // Вызывается служебным потоком при изменении файла настроек
    void UpdateConfig(DriverRuntimeConfig newConfig) {
        auto newPtr = std::make_shared(newConfig);
        std::atomic_store_explicit(&m_activeConfig, newPtr, std::memory_order_release);
    }

    // Вызывается в горячем цикле потока инъекции
    std::shared_ptr AcquireConfig() const noexcept {
        return std::atomic_load_explicit(&m_activeConfig, std::memory_order_acquire);
    }

private:
    std::shared_ptr m_activeConfig{
        std::make_shared()
    };
};

7. Инъекция курсора в osu! и арбитраж устройств

7.1. Разделение подсистем ввода stable и lazer

7.2. Интерфейсы виртуального HID ядра (VTD vs VHID)

Инъекция ДОЛЖНА производиться через готовые виртуальные шины с официальной цифровой подписью:

1. OpenTabletDriver VirtualTabletDriver (VTD): Подписан через механизм Microsoft Attestation. Принимает координаты через DeviceIoControl.
2. Nefarius Virtual HID Framework (VHID): Официально сертифицированная WHQL-шина ядра, эмулирующая стандартный дигитайзер.

8. Системный таймер и планировщик Windows

8.1. Прецизионный таймер высокого разрешения

Устаревший вызов timeBeginPeriod(1) меняет глобальный тик системы и повышает энергопотребление. Разработчик ДОЛЖЕН использовать документированный флаг таймера высокого разрешения:

HANDLE CreateSubmillisecondTimer() noexcept {
    return CreateWaitableTimerExW(
        nullptr,
        nullptr,
        CREATE_WAITABLE_TIMER_HIGH_RESOLUTION | CREATE_WAITABLE_TIMER_MANUAL_RESET,
        TIMER_ALL_ACCESS
    );
}

void SleepPreciseNanoseconds(HANDLE hTimer, int64_t hundredsOfNanoseconds) noexcept {
    LARGE_INTEGER dueTime;
    dueTime.QuadPart = -hundredsOfNanoseconds; // Отрицательное значение = относительное время
    SetWaitableTimer(hTimer, &dueTime, 0, nullptr, nullptr, FALSE);
    WaitForSingleObject(hTimer, INFINITE);
}

8.2. Настройка реестра для мультимедиа-сервиса (MMCSS)

Для исключения системного ограничения процессорного времени мультимедиа-потоков настраиваются параметры системного профиля:

• Раздел реестра: HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Multimedia\SystemProfile
• Параметр SystemResponsiveness (DWORD): 0 (выделять 100% процессорных квантов сервису мультимедиа вместо резерва 20% на системные службы).
• Параметр NoLazyMode (DWORD): 1 (отключение отложенного планирования квантов).

9. Управление питанием и аппаратная топология

9.1. Топология шины USB

Порты USB на материнской плате делятся на два типа:

1. CPU-Root: Разъёмы, подключенные к контроллеру процессора напрямую.
2. PCH/Chipset: Разъёмы, работающие через чипсет материнской платы по общей шине DMI.

Требование: Планшет ОБЯЗАН подключаться исключительно в порты CPU-Root. Подключение через чипсетные порты, хабы монитора или внешние удлинители вносит дополнительную задержку буферизации (от 0.3 до 1.2 мс).

9.2. Отключение энергосбережения USB и процессора

• USB Selective Suspend: ДОЛЖНО быть отключено в плане электропитания Windows и в параметрах корневых концентраторов USB в Диспетчере устройств.
• Глубокие состояния сна ядер процессора (C-States C1E, C6, C8): Задержка выхода ядра из сна достигает 80 мкс. Для ядер, выделенных под драйвер, СЛЕДУЕТ ограничить состояния сна уровнем C0/C1.

10. Отказоустойчивость и горячее подключение

Потеря пакета или внезапное отключение кабеля не должны нарушать работу конвейера:

void HandleDeviceArrivalRemoval(HWND hWnd, WPARAM wParam, LPARAM lParam) {
    if (wParam == DBT_DEVICEREMOVECOMPLETE) {
        g_DeviceConnected.store(false, std::memory_order_release);
        CancelIoEx(g_hDevice, nullptr);
        CloseHandle(g_hDevice);
    } else if (wParam == DBT_DEVICEARRIVAL) {
        // Повторная инициализация дескриптора и очереди IOCP
        ReinitializeDevice();
    }
}

11. Профилирование и измерение задержки

11.1. Аппаратный замер (Click-to-Photon)

Программные замеры не фиксируют время обработки контроллера сенсора и отклик матрицы монитора:

• Методика 1 (Высокоскоростная съёмка): Камера со скоростью 1000–2400 кадров/с фиксирует момент физического касания наконечником пера поверхности планшета и первый пиксельный сдвиг курсора на дисплее (с отключенной вертикальной синхронизацией).
• Методика 2 (Аппаратный стенд): Аппаратный анализатор шины логирует момент отправки USB-пакета планшетом, а высокоскоростной фотодиод на экране фиксирует изменение яркости пикселя под курсором.

12. Сборка проекта и флаги компилятора

12.1. Конфигурация CMakeLists.txt

cmake_minimum_required(VERSION 3.25)
project(NativeTabletDriver CXX)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

if (MSVC)
    add_compile_options(
        /O2                 # Максимальная скорость
        /Ob3                # Агрессивный инлайнинг
        /Oi /Ot             # Генерация быстрых процессорных инструкций
        /GL                 # Whole Program Optimization
        /fp:precise         # Точная математика с плавающей точкой
        /arch:AVX2          # Аппаратный AVX2 и FMA
        /EHs-c- /GR-        # Полное отключение исключений и RTTI
        /GS-                # Отключение проверок стека в цикле обработки
    )
    add_link_options(/LTCG) # Link-Time Code Generation
endif()

add_executable(NativeTabletDriver 
    src/main.cpp 
    src/hid_ingestion.cpp 
    src/dsp_filter.cpp 
    src/virtual_hid_injector.cpp
)

target_link_libraries(NativeTabletDriver PRIVATE hid avrt setupapi)

13. Подписывание и безопасность

13.1. Блокировка режима Testsigning

Принудительное включение тестовой подписи командой:

bcdedit /set testsigning on

является критической ошибкой настройки системы игрока:

1. Полная блокировка онлайн-функций в osu!stable: Ванильный клиент игры определяет наличие флага тестового режима Windows и полностью блокирует онлайн-функциональность — авторизацию на официальных серверах Bancho, отправку результатов (субмит скоров) и многопользовательский режим.
2. Сторонние античиты соревновательных игр: Системы Vanguard (Valorant), Easy Anti-Cheat (Apex Legends, Fortnite) и BattlEye принудительно запрещают запуск игр при активном флаге testsigning.
3. Безопасность системы: Требуется отключение Secure Boot, что снижает базовую защищенность ядра ОС.

13.2. Архитектура работы без тестового режима

Драйвер функционирует исключительно в обычном пользовательском режиме со включенным Secure Boot. Трансляция координат осуществляется через официально подписанные шины:

• Использование интерфейса OpenTabletDriver VirtualTabletDriver.sys (подпись Microsoft Attestation).
• Использование интерфейса Nefarius Virtual HID Driver (официальный сертификат Microsoft WHQL).

14. Чеклист перед релизом

• : Дескриптор открыт с dwShareMode = 0 для подавления конфликтов с osu!lazer.
• : Системная очередь усечена до двух отчетов или активен ring-drain сброс.
• : Межпоточный обмен переведён на 128-битный std::atomic.
• : Потокам назначен профиль MMCSS Pro Audio, EcoQoS принудительно отключен.
• : Потоки привязаны к физическим P-Cores, ядро Core 0 исключено.
• : Фильтр 1-Euro динамически пересчитывает параметры по непрерывной дельте времени.
• : Маппинг рабочей зоны учитывает границы Virtual Desktop и использует инструкцию FMA.
• : Перезагрузка настроек работает без мьютексов.
• : Режим testsigning выключен, онлайн-функции osu! и античиты не блокируются.
• В цикле обработки пакетов полностью отсутствуют динамические аллокации памяти.

15. Источники и верификация

• Microsoft Learn: CreateWaitableTimerExW function & High-Resolution Timer Support.
• Microsoft Learn: PROCESS_POWER_THROTTLING_STATE structure & EcoQoS architecture in Windows 11.
• WDK Documentation: HidD_SetNumInputBuffers & Virtual HID Framework (VHF).
• Géry Casiez, Nicolas Roussel, Daniel Vogel: 1 € Filter: A Simple Speed-based Low-pass Filter for Noisy Input in Interactive Systems.
• OpenTabletDriver Project: Архитектура межпроцессного взаимодействия и спецификации VirtualTabletDriver.

16. Лицензия

MIT License

Copyright (c) 2026 shuvi

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.