Request for advice for future PR: establishing conventions for Bluetooth HCI Vendor-Specific Commands (VSCs)

In Bluetooth over HCI, there is a notion of "Vendor-Specific Commands". These have the Opcode Group Field (OGF) set to 0x3F (max value of all 1s for this 6-bit field), and then have the Opcode Command Field (10 bits) set to whatever the vendor wants. Vendors use these to implement chip-specific functionality, which is not outlined in the HCI spec. E.g. common examples of this are things like setting the BDADDR, transmit power, or allowing memory read/write to a controller's memory.

I'd like to submit a future PR to include VSCs for Realtek which I REed (e.g. for use with scapy-usbbluetooth). But there are also VSCs which are publicly documented (e.g. see here for TI or here (auto-downloading PDF) for Cypress) which I could imagine adding eventually.

Before I submit the PR, I'd like to discuss how you'd like this to be handled in an extensible way. I see 4 possible options:

1. Just put VSCs in bluetooth.py where all the existing HCI stuff is.
2. Create a new file (bluetoothVSC.py?) which gets all VSCs for all vendors.
3. Create a per-vendor file (bluetoothVSCRealtek.py, bluetoothVSCTexasInstruments.py, etc), which has only individual companies' VSCs.

How would you prefer this be handled?

An important thing to consider is that VSCs will necessarily conflict with each other between vendors. I.e. vendor 1 will tend to start with OGF=0x3F, OCF=0x001, and vendor 2 may well do the same. So I don't know whether that will cause a problem for Scapy, but I'm assuming it won't, and people would just cast the VSCs to whichever vendor interpretation they want and that it would be handled fine?

There would also be Vendor Specific Events (VSEs) which are the definitions of the data that comes back from VSCs (e.g. a read-RAM could be limited to 4 bytes response, or variable length up to 251 bytes.)

Example Realtek VSCs

Scapy definition:

# Tested and known-working definitions
class HCI_Cmd_VSC_Realtek_Read_Mem(Packet):
    name = "Realtek Read Memory"
    fields_desc = [
        ByteField("size", 0x20),
        XLEIntField("address", 0x80000000)
    ]

bind_layers(HCI_Command_Hdr, HCI_Cmd_VSC_Realtek_Read_Mem, ogf=0x3f, ocf=0x0061)

Scapy definition:

# Tested and known-working definitions
class HCI_Cmd_VSC_Realtek_Write_Mem(Packet):
    name = "Realtek Write Memory"
    fields_desc = [
        ByteField("size", 0x20),
        XLEIntField("address", 0x80000000),
        XLEIntField("data_to_write", 0x33221100)
    ]

bind_layers(HCI_Command_Hdr, HCI_Cmd_VSC_Realtek_Write_Mem, ogf=0x3f, ocf=0x0062)

Start with the existing HCI definitions in bluetooth.py and review the Realtek VSC examples in this issue, including their OGF/OCF bindings and packet fields. Before implementing anything, confirm with maintainers how vendor-specific commands and events should be organized and how conflicting vendor opcodes should be handled. Done means an agreed convention that makes a future VSC contribution actionable.