From: Luiz Augusto von Dentz <luiz.von.dentz@xxxxxxxxx>
This adds initial documentation for HCI sockets.
---
Makefile.am | 6 +--
doc/hci.rst | 152 ++++++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 155 insertions(+), 3 deletions(-)
create mode 100644 doc/hci.rst
diff --git a/Makefile.am b/Makefile.am
index 3eb0a5302737..3ced4f87a56e 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -352,7 +352,7 @@ CLEANFILES += $(builtin_files)
if MANPAGES
man_MANS += src/bluetoothd.8
-man_MANS += doc/l2cap.7 doc/rfcomm.7
+man_MANS += doc/hci.7 doc/l2cap.7 doc/rfcomm.7
man_MANS += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \
doc/org.bluez.DeviceSet.5 doc/org.bluez.AgentManager.5 \
doc/org.bluez.Agent.5 doc/org.bluez.ProfileManager.5 \
@@ -386,7 +386,7 @@ man_MANS += doc/org.bluez.obex.Client.5 doc/org.bluez.obex.Session.5 \
doc/org.bluez.obex.Image.5
endif
manual_pages += src/bluetoothd.8
-manual_pages += doc/l2cap.7 doc/rfcomm.7
+manual_pages += doct/hci.7 doc/l2cap.7 doc/rfcomm.7
manual_pages += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \
doc/org.bluez.DeviceSet.5 doc/org.bluez.AgentManager.5 \
doc/org.bluez.Agent.5 doc/org.bluez.ProfileManager.5 \
@@ -465,7 +465,7 @@ EXTRA_DIST += doc/mgmt-api.txt \
doc/health-api.txt \
doc/sap-api.txt
-EXTRA_DIST += doc/l2cap.rst
+EXTRA_DIST += doc/hci.rst doc/l2cap.rst doc/rfcomm.rst
EXTRA_DIST += doc/org.bluez.Adapter.rst doc/org.bluez.Device.rst \
doc/org.bluez.DeviceSet.rst doc/org.bluez.AgentManager.rst \
diff --git a/doc/hci.rst b/doc/hci.rst
new file mode 100644
index 000000000000..d7f192a27d19
--- /dev/null
+++ b/doc/hci.rst
@@ -0,0 +1,152 @@
+===
+hci
+===
+
+----------------------
+Bluetooth HCI protocol
+----------------------
+
+:Version: BlueZ
+:Copyright: Free use of this software is granted under ther terms of the GNU
+ Lesser General Public Licenses (LGPL).
+:Date: October 2024
+:Manual section: 7
+:Manual group: Linux System Administration
+
+SYNOPSIS
+========
+
+.. code-block::
+
+ #include <sys/socket.h>
+ #include <bluetooth/bluetooth.h>
+ #include <bluetooth/hci.h>
+
+ hci_socket = socket(PF_BLUETOOTH, SOCK_RAW, BTPROTO_HCI);
+
+DESCRIPTION
+===========
+
+Bluetooth Host Controller Interface (HCI) is the standard protocol to
+communicate with Bluetooth adapters. HCI protocol provides a uniform command
+method for the Host to access Controller capabilities and to control connections
+to other Controllers.
+
+SOCKET ADDRESS
+==============
+
+.. code-block::
+
+ struct sockaddr_hci {
+ sa_family_t hci_family;
+ unsigned short hci_dev;
+ unsigned short hci_channel;
+ };
+
+Possible values for hci_channel:
+
+.. csv-table::
+ :header: "Define", "Value", "Description"
+ :widths: auto
+
+ **HCI_CHANNEL_RAW**, 0x00, Raw channel - Used for raw HCI communication
+ **HCI_CHANNEL_USER**, 0x01, User channel - Used for userspace HCI communication (disables kernel processing)
+ **HCI_CHANNEL_MONITOR**, 0x02, Monitor channel - Used for monitoring HCI traffic (btmon(1))
+ **HCI_CHANNEL_CONTROL**, 0x03, Control channel - Used to manage local adapters (bluetoothd(7))
+ **HCI_CHANNEL_LOGGING**, 0x04, Logging channel - Used to inject logging messages (bluetoothd(7))
+
+Example:
+
+.. code-block::
+
+ struct sockaddr_hci addr;
+
+ memset(&addr, 0, sizeof(addr));
+ addr.hci_family = AF_BLUETOOTH;
+ addr.hci_dev = HCI_DEV_NONE;
+ addr.hci_channel = HCI_CHANNEL_CONTROL;
+
+SOCKET OPTIONS
+==============
+
+The socket options listed below can be set by using **setsockopt(2)** and read
+with **getsockopt(2)** with the socket level set to SOL_BLUETOOTH or SOL_HCI
+(HCI_FILTER).
+
+HCI_FILTER (since Linux 2.6)
+----------------------------
+
+Filter by HCI events, requires hci_channel to be set to HCI_CHANNEL_RAW,
+possible values:
+
+.. code-block::
+
+ struct hci_filter {
+ uint32_t type_mask;
+ uint32_t event_mask[2];
+ uint16_t opcode;
+ };
+
+Example:
+
+.. code-block::
+
+ struct hci_filter flt;
+
+ memset(&flt, 0, sizeof(flt));
+ flt.type_mask = 1 << BT_H4_EVT_PKT;
+ flt.event_mask[0] = 0xffffffff;
+ flt.event_mask[1] = 0xffffffff;
+
+ setsockopt(fd, SOL_HCI, HCI_FILTER, &flt, sizeof(flt));
+
+BT_SNDBUF (since Linux 5.16)
+----------------------------
+
+Set send buffer size, requires hci_channel to be set to HCI_CHANNEL_MONITOR,
+HCI_CHANNEL_CONTROL or HCI_CHANNEL_LOGGING.
+
+Default value is 1028.
+
+Example:
+
+.. code-block::
+
+ uint16_t mtu = UINT16_MAX;
+ int err;
+
+ err = setsockopt(fd, SOL_BLUETOOTH, BT_SNDMTU, &mtu, sizeof(mtu));
+
+BT_RCVBUF (since Linux 5.16)
+----------------------------
+
+Set receive buffer size, requires hci_channel to be set to HCI_CHANNEL_MONITOR,
+HCI_CHANNEL_CONTROL or HCI_CHANNEL_LOGGING.
+
+Default value is 1028.
+
+Example:
+
+.. code-block::
+
+ uint16_t mtu;
+ socklen_t len;
+ int err;
+
+ len = sizeof(mtu);
+ err = getsockopt(sock, SOL_BLUETOOTH, BT_RCVMTU, mtu, &len);
+
+RESOURCES
+=========
+
+http://www.bluez.org
+
+REPORTING BUGS
+==============
+
+linux-bluetooth@xxxxxxxxxxxxxxx
+
+SEE ALSO
+========
+
+socket(7)
--
2.47.0
