docs: итог KBD-1 — что лечит плотный опрос и что осталось

Ручная проверка пользователем: стало значительно лучше, но редкие пропуски
стрелок при зажатом Shift всё же ощущаются.  Счётчики на 35 нажатиях подряд
потерь не показали, то есть остаточная частота заметно ниже прежних ~15 %.
Задача отложена до финальной полировки программы (решение пользователя) —
для работы клавиатура пригодна.

Записано, где именно осталась дыра, чтобы не начинать с нуля: idle-хук
покрывает простой (~2/3 кадра), а в занятой трети DI-окно одного
accel-прохода доходит до ~650 мкс при допуске FIFO ~300 мкс — пачка байт,
целиком попавшая в такое окно, ещё может потерять байт.  Порядок действий
на возврат: вызовы между блитами занятой фазы, замер тем же счётным методом
от 50 нажатий, и только потом рычаги вне нашего кода (Scan Code Set 3 через
BIOS $EA — в MAME непроверяемо; общий m_irq_off_timer в драйвере).

Заодно сняты оговорки «плотный опрос ещё не подтверждён замером» в
kbd_raw.h и libc-reference.md — теперь там штатный рецепт через
gfx_set_idle_hook.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

libc/include/kbd_raw.h

@@ -68,14 +68,18 @@ void kbd_raw_sync(void);
  * этом переполняют FIFO: теряется make («нажатие не сработало») или break
  * (залипание).
  *
- * ЧЕСТНАЯ ОГОВОРКА ПО ЭФФЕКТИВНОСТИ (замер 2026-08-01, PoP roomtest,
- * см. applications/PoP/roomtest/TASKS.md, KBD-1): расстановка «несколько
- * вызовов за кадр, после тяжёлых фаз» НЕ ДАЁТ НИЧЕГО — потери те же, что
- * без неё.  Такие вызовы попадают в участки, где прерывания и так
- * разрешены, и лишь дублируют трамплин.  Смысл появляется только у
- * ПЛОТНОГО опроса (в цикле ожидания, десятки-сотни раз за кадр), и это
- * ещё не подтверждено замером.  Не ставить эту функцию в игровой цикл
- * «на всякий случай» — сначала померить.
+ * КАК ЕЁ ЗВАТЬ (замеры 2026-08-01, PoP roomtest — см.
+ * applications/PoP/roomtest/TASKS.md, KBD-1):
+ *  - «несколько вызовов за кадр, после тяжёлых фаз» НЕ ДАЁТ НИЧЕГО —
+ *    потери те же, что без них: такие вызовы попадают в участки, где
+ *    прерывания и так разрешены, и лишь дублируют трамплин;
+ *  - работает только ПЛОТНЫЙ опрос, порядка раза в 0.5 мс.  Столько
+ *    времени есть даром в ожидании кадра, поэтому штатный способ —
+ *    повесить эту функцию idle-хуком графики:
+ *        gfx_set_idle_hook(my_poll_wrapper);   // <gfx.h>
+ *    Проверено: 35 нажатий стрелки с зажатым Shift → 35 дошедших make
+ *    против 9 из 10 без хука.
+ * Не ставить в игровой цикл «на всякий случай» — сначала померить.
  *
  * Тело идёт под DI и БЕЗУСЛОВНО делает EI на выходе: рассчитано на вызов
  * из главного цикла, из ISR звать нельзя. */