/*
  StarForth — Steady-State Virtual Machine Runtime
  Copyright (c) 2023–2026 Robert A. James. All rights reserved.
  Licensed under the StarForth License, Version 1.0.
 */

/**
 * usb_kbd.h - a USB boot-protocol keyboard's keys, as key events
 * (2026-10-14, boards/BRINGUP.md A3; usb_kbd.c).
 *
 * The xHCI driver hands each 8-byte boot report here; the keys pressed
 * and released since the report before come out as Linux input keycodes,
 * the namespace every keyboard in this kernel already speaks
 * (sk_key_event_poll(), keyboard_words.c).
 */

#ifndef STARKERNEL_USB_KBD_H
#define STARKERNEL_USB_KBD_H

#include <stdint.h>

/* One boot report: byte 0 the modifier bits, byte 1 reserved, bytes 2-7
 * up to six keys held (HID usage IDs). `len` below 3 is ignored. `prev`
 * is that keyboard's own last report, 8 bytes, kept by the caller -- each
 * keyboard is compared with itself, never with another. */
void usb_kbd_report(uint8_t prev[8], const uint8_t *report, uint32_t len);

/* The keyboard has gone: every key it still held is released, and its
 * last report forgotten -- no Shift stays down after it. */
void usb_kbd_forget(uint8_t prev[8]);

/* The next key event: 1 with *keycode (Linux) and *pressed (1/0), or 0. */
int usb_kbd_pop_event(uint16_t *keycode, int *pressed);

/* The lock lights (boot output report bits, HID 1.11 appendix B.1). The
 * console says which locks are on; the xHCI driver sends them to each
 * keyboard with SET_REPORT whenever they differ from what it last sent. */
#define USB_KBD_LED_NUM    0x01u
#define USB_KBD_LED_CAPS   0x02u
#define USB_KBD_LED_SCROLL 0x04u
void usb_kbd_set_leds(uint8_t leds);
/* The lights every keyboard should show. Each keyboard's driver state
 * holds what that keyboard was last sent. */
uint8_t usb_kbd_leds_wanted(void);

#endif /* STARKERNEL_USB_KBD_H */