/*
  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. */
void usb_kbd_report(const uint8_t *report, uint32_t len);

/* Forgets the keys held: the keyboard has gone. */
void usb_kbd_reset(void);

/* 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 the
 * 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);
/* 1 and the lights to send if they changed since last sent, else 0. */
int usb_kbd_leds_pending(uint8_t *leds);
/* The driver has sent these. */
void usb_kbd_leds_sent(uint8_t leds);

#endif /* STARKERNEL_USB_KBD_H */