diff mbox series

[BlueZ,v1] doc: Add initial HCI(7) documentation

Message ID 20241018193730.1177359-1-luiz.dentz@gmail.com
State New
Headers show
Series [BlueZ,v1] doc: Add initial HCI(7) documentation | expand

Commit Message

Luiz Augusto von Dentz Oct. 18, 2024, 7:37 p.m. UTC 
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>

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

Comments

bluez.test.bot@gmail.com Oct. 18, 2024, 9:39 p.m. UTC | #1 
This is automated email and please do not reply to this email!

Dear submitter,

Thank you for submitting the patches to the linux bluetooth mailing list.
This is a CI test results with your patch series:
PW Link:https://patchwork.kernel.org/project/bluetooth/list/?series=900880

---Test result---

Test Summary:
CheckPatch                    PASS      0.64 seconds
GitLint                       PASS      0.32 seconds
BuildEll                      PASS      24.68 seconds
BluezMake                     PASS      1643.78 seconds
MakeCheck                     PASS      13.28 seconds
MakeDistcheck                 FAIL      9.03 seconds
CheckValgrind                 PASS      252.62 seconds
CheckSmatch                   PASS      356.76 seconds
bluezmakeextell               PASS      120.64 seconds
IncrementalBuild              PASS      1413.01 seconds
ScanBuild                     PASS      1016.29 seconds

Details
##############################
Test: MakeDistcheck - FAIL
Desc: Run Bluez Make Distcheck
Output:

make[2]: *** No rule to make target 'doct/hci.7', needed by 'distdir-am'.  Stop.
make[2]: *** Waiting for unfinished jobs....
make[1]: *** [Makefile:12189: distdir] Error 2
make: *** [Makefile:12265: dist] Error 2


---
Regards,
Linux Bluetooth
patchwork-bot+bluetooth@kernel.org Oct. 21, 2024, 8:20 p.m. UTC | #2 
Hello:

This patch was applied to bluetooth/bluez.git (master)
by Luiz Augusto von Dentz <luiz.von.dentz@intel.com>:

On Fri, 18 Oct 2024 15:37:30 -0400 you wrote:
> From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
> 
> 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

Here is the summary with links:
  - [BlueZ,v1] doc: Add initial HCI(7) documentation
    https://git.kernel.org/pub/scm/bluetooth/bluez.git/?id=8572f2430980

You are awesome, thank you!
diff mbox series

Patch

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@vger.kernel.org
+
+SEE ALSO
+========
+
+socket(7)