/*
  StarForth — Steady-State Virtual Machine Runtime

  Copyright (c) 2023–2025 Robert A. James
  All rights reserved.

  Licensed under the StarForth License, Version 1.0
*/

#ifndef KEYBOARD_WORDS_H
#define KEYBOARD_WORDS_H

#include "vm.h"

/**
 * @defgroup keyboard_words Keyboard Words
 * @{
 *
 * @brief Raw hardware-boundary FORTH word for verifying the interrupt-driven
 * keyboard path (FABRIC.md item 4.3.5). Deliberately a diagnostic peek at
 * the raw scancode ring buffer -- no set-2 translation, no REPL wiring.
 * Those belong to the later REPL keyboard-input work noted in FABRIC.md.
 *
 * Kernel-only, amd64-only today (i8042 is amd64 hardware); no-op elsewhere
 * so dictionary parity across all three architectures is unaffected.
 *
 * @par KBD-SCAN ( -- c -1 | 0 )
 * Pop one raw scancode off the interrupt-fed ring buffer. Pushes the
 * scancode and -1 (true) if one was available, or just 0 (false) if the
 * buffer was empty.
 *
 * @par KBD-DEBUG ( -- isr_count spurious_count )
 * Standing diagnostic: count of real keyboard IRQs serviced and count of
 * LAPIC spurious-vector interrupts, both since boot.
 *
 * @par VKBD-EVENT ( -- code value -1 | 0 )
 * Item 4.3.5c. Pop one decoded EV_KEY event (Linux input-event code/value
 * pair) off the virtio-input interrupt-fed ring buffer. Kernel-only,
 * riscv64-only today (virtio-keyboard-pci); no-op elsewhere.
 *
 * @par VKBD-DEBUG ( -- isr_count )
 * Standing diagnostic: count of virtio-input ISR invocations since boot.
 * @}
 */

void register_keyboard_words(VM *vm);

#endif /* KEYBOARD_WORDS_H */