/* SPDX-License-Identifier: LicenseRef-Starship-1.0
 * Copyright (c) 2023-2026 Robert A. James
 */
/* usb_config.h -- a USB configuration descriptor set, read: what xhci.c's event loop needs to know
 * of a device (its first interface, and that interface's endpoints). Moved out of the loop's
 * XHCI_XFER_CONFIG_DESC_FULL case unchanged, so it can be tested on the host
 * (kernel/tests/test_usb_config.c; docs/v4.0.0/plans/2026-11-12-kernel-host-tests.md).
 */
#ifndef STARKERNEL_USB_CONFIG_H
#define STARKERNEL_USB_CONFIG_H

#include <stdint.h>

#define USB_CONFIG_NO_INTERFACE 0   /* no Interface descriptor in the set */
#define USB_CONFIG_MSC          1   /* Mass Storage / SCSI / Bulk-Only Transport */
#define USB_CONFIG_KBD          2   /* a HID boot keyboard */
#define USB_CONFIG_OTHER        3   /* anything else -- not used */

typedef struct {
    int      kind;                                /* USB_CONFIG_* */
    uint8_t  iface_class, iface_subclass, iface_protocol;
    uint8_t  config_value;                        /* bConfigurationValue, for SET_CONFIGURATION */
    uint8_t  bulk_in_ep, bulk_out_ep;             /* USB_CONFIG_MSC: 0 when not found */
    uint16_t bulk_in_max, bulk_out_max;
    uint8_t  hid_iface;                           /* USB_CONFIG_KBD */
    uint8_t  hid_ep, hid_interval;                /* hid_ep 0 when not found */
    uint16_t hid_max;
} usb_config_t;

/* Read the first `len` bytes of a configuration descriptor set (the Configuration descriptor and
 * the Interface and Endpoint descriptors after it). Only the first Interface descriptor counts;
 * a descriptor with bLength 0 ends the walk. Never reads past `len`. */
void usb_config_parse(const uint8_t *desc, uint16_t len, usb_config_t *out);

/* After the configuration descriptor's first 9 bytes: how many bytes of the whole set to ask
 * for, given its wTotalLength and the buffer's size `cap` -- 0 when wTotalLength is 9 or less (the
 * device is not used: #170); *cut set to 1 when the set is longer than the buffer (#171). */
uint16_t usb_config_request_length(uint16_t total, uint16_t cap, int *cut);

#endif