BLUETOOTH(9)

✨ NAME ✨

This is the BLUETOOTH(9) man page, and it's literally the glow-up guide for talking to Bluetooth devices from the kernel. The official vibe? Bluetooth Device/Protocol API. No cap. 💅

🦋 SYNOPSIS 🦋

Here's the include vibe, bestie:

#include <netbt/bluetooth.h>
#include <netbt/hci.h>
#include <netbt/l2cap.h>
#include <netbt/rfcomm.h>

Then the function prototypes, all iconic:

struct hci_unit *
hci_attach(const struct hci_if *hci_if, device_t dev, uint16_t flags);

void
hci_detach(struct hci_unit *unit);

void
hci_input_event(struct hci_unit *unit, struct mbuf *m);

void
hci_input_acl(struct hci_unit *unit, struct mbuf *m);

void
hci_input_sco(struct hci_unit *unit, struct mbuf *m);

int
btproto_attach(btproto_handle *, const struct btproto *proto,
    void *ref);

int
btproto_bind(btproto_handle, struct sockaddr_bt *addr);

int
btproto_sockaddr(btproto_handle, struct sockaddr_bt *addr);

int
btproto_connect(btproto_handle, struct sockaddr_bt *addr);

int
btproto_peeraddr(btproto_handle, struct sockaddr_bt *addr);

int
btproto_disconnect(btproto_handle, int linger);

int
btproto_detach(btproto_handle *);

int
btproto_listen(btproto_handle);

int
btproto_send(btproto_handle, struct mbuf *mbuf);

int
btproto_rcvd(btproto_handle, size_t space);

int
btproto_setopt(btproto_handle, int optarg, void *arg);

int
btproto_getopt(btproto_handle, int optarg, void *arg);

💫 DESCRIPTION 💫

The Bluetooth Protocol Stack gives you socket-based access to Bluetooth devices — like, it's the whole vibe check for making Bluetooth stuff work. This doc? It's for device driver access to the stack from below (yes, from below bestie, we're going deep) and also the general Bluetooth Protocol/Service API for layering stuff above existing Bluetooth Protocols. It's giving full-stack energy. 🔥

🎀 DATA TYPES 🎀

So if you're a device driver attaching to the Bluetooth Protocol Stack, you gotta pass a pointer to a struct hci_if — that's defined in <netbt/hci.h> and it holds the driver info, like this:

struct hci_if {
        int     (*enable)(device_t);
        void    (*disable)(device_t);
        void    (*output_cmd)(device_t, struct mbuf *);
        void    (*output_acl)(device_t, struct mbuf *);
        void    (*output_sco)(device_t, struct mbuf *);
        void    (*get_stats)(device_t, struct bt_stats *, int);
        int     ipl;
};

Real talk: statistics counters should be updated by the device after packets have been transmitted or received, or when errors occur. Don't skip that, bestie. 📊

And here's the stats struct, struct bt_stats:

struct bt_stats {
        uint32_t        err_tx;
        uint32_t        err_rx;
        uint32_t        cmd_tx;
        uint32_t        evt_rx;
        uint32_t        acl_tx;
        uint32_t        acl_rx;
        uint32_t        sco_tx;
        uint32_t        sco_rx;
        uint32_t        byte_tx;
        uint32_t        byte_rx;
};

Now, Bluetooth Protocol layers that attach above the Bluetooth Protocol Stack? They use the struct btproto data type — defined in <netbt/bluetooth.h> — and it's packed with function callbacks that the protocol layer should initialize before attaching to the protocol it uses. Like, set these up first, okay? 💅

struct btproto {
        void (*connecting)(void *);
        void (*connected)(void *);
        void (*disconnected)(void *, int);
        void *(*newconn)(void *, struct sockaddr_bt *, struct sockaddr_bt *);
        void (*complete)(void *, int);
        void (*linkmode)(void *, int);
        void (*input)(void *, struct mbuf *);
};

🛠️ FUNCTIONS 🛠️

🌟 Bluetooth Device API Functions 🌟

These are the functions related to the Bluetooth Device API. Let's go. 👑

• hci_attach(hci_if, dev) — Attach Bluetooth HCI device dev to the protocol stack in the manner described by hci_if. Driver quirks? You can register them by passing the corresponding BTF_xxxx flag in the flags argument. hci_attach() will return a struct hci_unit handle — keep that, you'll pass it to the protocol stack in other calls. It's giving main character handle energy. 🫶
• hci_detach(unit) — Detach Bluetooth HCI unit from the device. Bye bestie 👋
• hci_input_event(unit, mbuf) — This function should be called by the device when it has an event packet to present to the protocol stack. It may be called from an interrupt routine at the ipl value given in the hci_if descriptor. So yes, interrupt vibes are allowed. ⚡
• hci_input_acl(unit, mbuf) — This function should be called by the device when it has an ACL data packet to present to the protocol stack. It may be called from an interrupt routine at the ipl value given in the hci_if descriptor. Same energy, different packet. 📦
• hci_input_sco(unit, mbuf) — This function should be called by the device when it has an SCO data packet to present to the protocol stack. It may be called from an interrupt routine at the ipl value given in the hci_if descriptor. SCO packets also get the interrupt glow-up. ✨
• (*enable)(dev) — This will be called when the protocol stack wishes to enable the device. Turn it on, bestie. 🔛
• (*disable)(dev) — This will be called when the protocol stack wishes to disable the device. Turn it off, periodt. 🔴
• (*output_cmd)(dev, mbuf) — Will be called to output command packets on the device. The device is responsible for arbitrating access to the output queue, and output commands should be sent asynchronously. The device owns the mbuf and should release it when sent. Don't forget to free it, fr fr. 🗑️
• (*output_acl)(dev, mbuf) — Will be called to output ACL data packets on the device. The device is responsible for arbitrating access to the output queue, and ACL data packets should be sent asynchronously. The device owns the mbuf and should release it when sent. Same rule: you own it, you release it. 🎯
• (*output_sco)(dev, mbuf) — Will be called to output SCO data packets on the device. The device is responsible for arbitrating access to the output queue, and SCO data packets should be sent asynchronously. When the SCO data packet has been placed on the device and the mbuf is no longer required, it should be returned to the Bluetooth protocol stack via the hci_complete_sco() call. So special rule for SCO, iykyk. 🎧
• (*get_stats)(dev, dest, flush) — Will be called when IO statistics are requested. The bt_stats structure dest should be filled in, and if the flush argument is true, statistics should be reset. So fill it up and maybe flush it, depending. 📈

💖 Bluetooth Protocol API Functions 💖

Now these function definitions are related to the Bluetooth Protocol API. Quick note bestie: the "btproto" prefix is representative only — the protocol being used will have a more specific prefix with prototypes being declared in the appropriate <netbt/btproto.h> file. So don't come for me if it's not literally btproto in your code. 😭

• btproto_attach(handle_ptr, proto, ref) — Allocate and initialize a new protocol object at the handle_ptr address that should subsequently be passed into the other functions. proto is a pointer to the btproto structure as described above containing relevant callbacks, and ref is the argument that will be supplied to those calls. It's like setting up your little protocol baby. 🍼
• btproto_bind(handle, addr) — Set the local address of the protocol object described by handle to addr. Local address = set. 📍
• btproto_sockaddr(handle, addr) — Copy the local address of the protocol object described by handle into addr. Copy-paste but make it kernel. 📋
• btproto_connect(handle, addr) — Initiate a connection by the protocol object described by handle to the remote device described by addr. This will result in a call to either proto->connected() or proto->disconnected(), and optionally proto->connecting() with the appropriate reference as given to btproto_attach(). So you'll get a callback, bestie. 🤝
• btproto_peeraddr(handle, addr) — Copy the remote address of the protocol object described by handle into addr. Remote address = copied. 🌐
• btproto_disconnect(handle, linger) — Schedule a disconnection by the protocol object described by handle. This will result in a call to proto->disconnected() with the appropriate reference when the connection is torn down. If linger is zero, the disconnection will be initiated immediately and any outstanding data may be lost. ⚠️ So like, zero linger means bye-bye data. Be careful.

⚠️ Warning bestie: if linger is zero, disconnection is immediate and outstanding data may be lost. That's not a drill. 💀

• btproto_detach(handle_ptr) — Detach the protocol object described by the value in the location of handle_ptr, and free any related memory. The pointer in the location is cleared. Clean up, clean up. 🧹
• btproto_listen(handle) — Use the protocol object described by handle as a listening post. This will result in calls to the proto->newconn() function when incoming connections are detected. It's giving waiting-for-the-call energy. ☎️
• btproto_send(handle, mbuf) — Send data on the connection described by the protocol object. Slide into their DMs with data. 📤
• btproto_rcvd(handle, space) — Indicate to the protocol that space is now available in the input buffers so that flow control may be deasserted. This should also be called to indicate initial buffer space. Note that space is an absolute value. So not a delta, bestie, an absolute value. 📏
• btproto_setopt(handle, optarg, arg) — Set options on the protocol object described by handle. Options = set. 🎛️
• btproto_getopt(handle, optarg, arg) — Get options for the protocol object described by handle. Options = got. 🎚️

🦋 Protocol Callbacks 🦋

These are the callbacks you initialize in struct btproto:

• (*connecting)(ref) — This function will be called when the protocol receives information that the connection described by ref is pending. Pending = not yet connected, just vibing. ⏳
• (*connected)(ref) — This function will be called when the connection described by ref is successful and indicates that data may now be sent. Success! Send data now. 🎉
• (*disconnected)(ref, error) — This function will be called when the connection described by ref is disconnected. It's over, bestie. 💔
• *(*newconn)(ref, laddr, raddr) — This function will be called when the protocol receives a new incoming connection on the local device described by laddr from the remote device described by raddr. The protocol should decide if it wishes to accept the connection and should attach and return a new instance of the relevant protocol handle or NULL. So you can accept or reject, your call. 👀
• (*complete)(ref, count) — This function will be called when the protocol has completed sending data. Complete will usually mean that the data has successfully left the device though for guaranteed protocols it can mean that the data has arrived at the other end and been acknowledged, and that count amount of data can be removed from the socket buffer. The units of the count value will be dependent on the protocol being used (e.g. RFCOMM is bytes, but L2CAP is packets). So count your units correctly, iykyk. 📦
• (*linkmode)(ref, mode) — This function will be called for established connections, when the link mode of the baseband link has changed. mode is the new mode. Link mode glow-up. 🔄
• (*input)(ref, mbuf) — This function is called to supply new data on the connection described by ref. New data incoming! 📥

✨ CODE REFERENCES ✨

okay so if you wanna go read the actual source (and honestly? mood 💅), here's where everything lives:

• the whole Bluetooth Protocol Stack is chillin' in the sys/netbt directory 🫶
• the Bluetooth Device API (all the stuff described above, bestie) is hanging out in sys/netbt/hci_unit.c
• for examples of the Bluetooth Protocol API, go peek at how the L2CAP upper layer in sys/netbt/l2cap_upper.c talks to either the L2CAP socket layer in sys/netbt/l2cap_socket.c or the bthidev(4) pseudo-device in sys/dev/bluetooth/bthidev.c 👀
• also!!! the RFCOMM upper layer in sys/netbt/rfcomm_upper.c and the RFCOMM socket layer in sys/netbt/rfcomm_socket.c — same vibes, different layer 🦋

like, the way this codebase is organised is genuinely giving "someone actually cared" and we love that for us 🌸

---

🌈 SEE ALSO 🌈

go touch grass in these other pages, iykyk:

• bluetooth(4)
• bt3c(4)
• bthidev(4)
• ubt(4)

---

🎀 HISTORY 🎀

okay so lore time 🫶 this Bluetooth Protocol Stack was written for NetBSD 4.0 by Iain Hibbert, under the sponsorship of Itronix, Inc. — iconic behaviour, no cap 👑

---

and that's a wrap on BLUETOOTH(9), bestie 💖 go forth and stack those protocols, you absolute main character 🦋✨

this page came from the Debian crew, dated November 20, 2007 — oldie but a goodie, lowkey historic 🎀