[PATCH BlueZ v2 06/12] doc: add btsnoop protocol manpage

[Luiz Augusto von Dentz <luiz.dentz@gmail.com>]

From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>

Add manpage-style RST doc/btsnoop-protocol.rst and synchronize opcodes
with src/shared/btsnoop.h.
---
 Makefile.am              |   7 +-
 doc/btsnoop-protocol.rst | 221 +++++++++++++++++++++++++++++++++++++++
 doc/btsnoop.txt          | 178 -------------------------------
 3 files changed, 225 insertions(+), 181 deletions(-)
 create mode 100644 doc/btsnoop-protocol.rst
 delete mode 100644 doc/btsnoop.txt

diff --git a/Makefile.am b/Makefile.am
index 064ee91698e2..dee6aa6d0d9b 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -367,7 +367,8 @@ CLEANFILES += $(builtin_files)
 
 if MANPAGES
 man_MANS += doc/bluetoothd.8
-man_MANS += doc/hci.7 doc/mgmt.7 doc/l2cap.7 doc/rfcomm.7 doc/sco.7 doc/iso.7
+man_MANS += doc/hci.7 doc/mgmt.7 doc/l2cap.7 doc/rfcomm.7 doc/sco.7 doc/iso.7 \
+		doc/btsnoop.7
 man_MANS += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \
 		doc/org.bluez.Bearer.LE.5 doc/org.bluez.Bearer.BREDR.5 \
 		doc/org.bluez.DeviceSet.5 doc/org.bluez.AgentManager.5 \
@@ -407,7 +408,7 @@ man_MANS += doc/org.bluez.ThermometerManager.5 \
 endif
 manual_pages += doc/bluetoothd.8
 manual_pages += doc/hci.7 doc/mgmt.7 doc/l2cap.7 doc/rfcomm.7 doc/sco.7 \
-		doc/iso.7
+		doc/iso.7 doc/btsnoop.7
 manual_pages += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \
 		doc/org.bluez.Bearer.LE.5 doc/org.bluez.Bearer.BREDR.5 \
 		doc/org.bluez.DeviceSet.5 doc/org.bluez.AgentManager.5 \
@@ -535,7 +536,7 @@ EXTRA_DIST += doc/org.bluez.ThermometerManager.rst \
 EXTRA_DIST += doc/pics-opp.txt doc/pixit-opp.txt \
 		doc/pts-opp.txt
 
-EXTRA_DIST += doc/btsnoop.txt
+EXTRA_DIST += doc/btsnoop-protocol.rst
 
 EXTRA_DIST += tools/magic.btsnoop
 
diff --git a/doc/btsnoop-protocol.rst b/doc/btsnoop-protocol.rst
new file mode 100644
index 000000000000..a875db63a9dd
--- /dev/null
+++ b/doc/btsnoop-protocol.rst
@@ -0,0 +1,221 @@
+=======
+btsnoop
+=======
+
+-------------------------------------------
+BTSnoop/Monitor protocol documentation
+-------------------------------------------
+
+:Version: BlueZ
+:Copyright: Free use of this software is granted under the terms of the GNU
+            Lesser General Public Licenses (LGPL).
+:Date: February 2026
+:Manual section: 7
+:Manual group: Linux System Administration
+
+SYNOPSIS
+========
+
+This document describes the BTSnoop/Monitor formats used to record and
+transport HCI/PHY traffic. The formats are used by tools such as btmon and the
+BlueZ btsnoop implementation.
+
+DESCRIPTION
+===========
+
+Opcode definitions
+------------------
+
+The following opcodes are used by the BTSnoop/Monitor formats. The numeric
+values match the definitions in ``src/shared/btsnoop.h``.
+
+.. list-table:: BTSnoop opcodes
+   :header-rows: 1
+
+   * - Name
+     - Code (dec)
+     - Code (hex)
+     - Meaning
+   * - BTSNOOP_OPCODE_NEW_INDEX
+     - 0
+     - 0x0000
+     - New controller index (parameters: type, bus, bdaddr, name)
+   * - BTSNOOP_OPCODE_DEL_INDEX
+     - 1
+     - 0x0001
+     - Deleted controller index
+   * - BTSNOOP_OPCODE_COMMAND_PKT
+     - 2
+     - 0x0002
+     - HCI Command packet
+   * - BTSNOOP_OPCODE_EVENT_PKT
+     - 3
+     - 0x0003
+     - HCI Event packet
+   * - BTSNOOP_OPCODE_ACL_TX_PKT
+     - 4
+     - 0x0004
+     - Outgoing ACL packet
+   * - BTSNOOP_OPCODE_ACL_RX_PKT
+     - 5
+     - 0x0005
+     - Incoming ACL packet
+   * - BTSNOOP_OPCODE_SCO_TX_PKT
+     - 6
+     - 0x0006
+     - Outgoing SCO packet
+   * - BTSNOOP_OPCODE_SCO_RX_PKT
+     - 7
+     - 0x0007
+     - Incoming SCO packet
+   * - BTSNOOP_OPCODE_OPEN_INDEX
+     - 8
+     - 0x0008
+     - HCI transport for the specified controller opened
+   * - BTSNOOP_OPCODE_CLOSE_INDEX
+     - 9
+     - 0x0009
+     - HCI transport for the specified controller closed
+   * - BTSNOOP_OPCODE_INDEX_INFO
+     - 10
+     - 0x000a
+     - Index information (parameters: bdaddr, manufacturer)
+   * - BTSNOOP_OPCODE_VENDOR_DIAG
+     - 11
+     - 0x000b
+     - Vendor diagnostic information
+   * - BTSNOOP_OPCODE_SYSTEM_NOTE
+     - 12
+     - 0x000c
+     - System note
+   * - BTSNOOP_OPCODE_USER_LOGGING
+     - 13
+     - 0x000d
+     - User logging (parameters: priority, ident_len, ident)
+   * - BTSNOOP_OPCODE_CTRL_OPEN
+     - 14
+     - 0x000e
+     - Control channel opened
+   * - BTSNOOP_OPCODE_CTRL_CLOSE
+     - 15
+     - 0x000f
+     - Control channel closed
+   * - BTSNOOP_OPCODE_CTRL_COMMAND
+     - 16
+     - 0x0010
+     - Control command packet
+   * - BTSNOOP_OPCODE_CTRL_EVENT
+     - 17
+     - 0x0011
+     - Control event packet
+   * - BTSNOOP_OPCODE_ISO_TX_PKT
+     - 18
+     - 0x0012
+     - Outgoing ISO packet
+   * - BTSNOOP_OPCODE_ISO_RX_PKT
+     - 19
+     - 0x0013
+     - Incoming ISO packet
+
+New Index
+---------
+
+Code: 0x0000
+
+Parameters:
+
+- Type (1 octet)
+- Bus (1 octet)
+- BD_Addr (6 octets)
+- Name (8 octets)
+
+This opcode indicates that a new controller instance with a given index was
+added. With some transports (for example a single TTY device) the index is
+implicitly 0.
+
+Deleted Index
+-------------
+
+Code: 0x0001
+
+Indicates that the controller with a specific index was removed.
+
+TTY-based protocol
+------------------
+
+The TTY protocol used by btmon with the ``--tty`` option is a little-endian
+packet format. Each packet uses this header::
+
+    struct tty_hdr {
+        uint16_t data_len;
+        uint16_t opcode;
+        uint8_t  flags;
+        uint8_t  hdr_len;
+        uint8_t  ext_hdr[0];
+    } __attribute__ ((packed));
+
+The payload starts at ``ext_hdr + hdr_len`` and has length
+``data_len - 4 - hdr_len``.
+
+Extended header format
+----------------------
+
+Each extension field is encoded as::
+
+    struct {
+        uint8_t type;
+        uint8_t value[length];
+    };
+
+Defined types:
+
+.. list-table:: Extended header types
+   :header-rows: 1
+
+   * - Type
+     - Length
+     - Meaning
+   * - 1
+     - 1 byte
+     - Command drops (dropped HCI command packets)
+   * - 2
+     - 1 byte
+     - Event drops (dropped HCI event packets)
+   * - 3
+     - 1 byte
+     - ACL TX drops
+   * - 4
+     - 1 byte
+     - ACL RX drops
+   * - 5
+     - 1 byte
+     - SCO TX drops
+   * - 6
+     - 1 byte
+     - SCO RX drops
+   * - 7
+     - 1 byte
+     - Other drops
+   * - 8
+     - 4 bytes
+     - 32-bit timestamp (1/10th ms)
+
+The drops fields contain the number of packets the implementation had to drop
+since the last reported drop count. Extension fields must be sorted by
+increasing ``type`` so unknown types can be skipped and the payload location
+discovered.
+
+RESOURCES
+=========
+
+http://www.bluez.org
+
+REPORTING BUGS
+==============
+
+linux-bluetooth@vger.kernel.org
+
+SEE ALSO
+========
+
+btmon(1)
diff --git a/doc/btsnoop.txt b/doc/btsnoop.txt
deleted file mode 100644
index 975a53f6dd44..000000000000
--- a/doc/btsnoop.txt
+++ /dev/null
@@ -1,178 +0,0 @@
-BTSnoop/Monitor protocol formats
-********************************
-
-Opcode definitions
-==================
-
-New Index
----------
-
-	Code:        0x0000
-	Parameters:  Type (1 Octet
-		     Bus (1 Octet)
-		     BD_Addr (6 Octets)
-		     Name (8 Octets)
-
-	This opcode indicates that a new controller instance with a
-	given index was added. With some protocols, like the TTY-based
-	one there is only a single supported controller, meaning the
-	index is implicitly 0.
-
-Deleted Index
--------------
-
-	Code:        0x0001
-
-	This opcode indicates that the controller with a specific index
-	was removed.
-
-Command Packet
---------------
-
-	Code:        0x0002
-
-	HCI command packet.
-
-Event Packet
-------------
-
-	Code:        0x0003
-
-	HCI event packet.
-
-ACL TX Packet
--------------
-
-	Code:        0x0004
-
-	Outgoing ACL packet.
-
-ACL RX Packet
--------------
-
-	Code:        0x0005
-
-	Incoming ACL packet.
-
-SCO TX Packet
---------------
-
-	Code:        0x0006
-
-	Outgoing SCO packet.
-
-SCO RX Packet
--------------
-
-	Code:        0x0007
-
-	Incomnig SCO packet.
-
-Open Index
-----------
-
-	Code:        0x0008
-
-	The HCI transport for the specified controller has been opened.
-
-Close Index
------------
-
-	Code:        0x0009
-
-	The HCI transport for the specified controller has been closed.
-
-Index Information
------------------
-
-	Code:        0x000a
-	Parameters:  BD_Addr (6 Octets)
-		     Manufacturer (2 Octets)
-
-	Information about a specific controller.
-
-Vendor Diagnostics
-------------------
-
-	Code:        0x000b
-
-	Vendor diagnostic information.
-
-System Note
------------
-
-	Code:        0x000c
-
-	System note.
-
-User Logging
-------------
-
-	Code:        0x000d
-	Parameters:  Priority (1 Octet)
-		     Ident_Length (1 Octet)
-		     Ident (Ident_Length Octets)
-
-	User logging information.
-
-
-TTY-based protocol
-==================
-
-This section covers the protocol that can be parsed by btmon when
-passing it the --tty parameter. The protocol is little endian, packet
-based, and has the following header for each packet:
-
-struct tty_hdr {
-	uint16_t data_len;
-	uint16_t opcode;
-	uint8_t  flags;
-	uint8_t  hdr_len;
-	uint8_t  ext_hdr[0];
-} __attribute__ ((packed));
-
-The actual payload starts at ext_hdr + hdr_len and has the length of
-data_len - 4 - hdr_len. Each field of the header is defined as follows:
-
-data_len:
-	This is the total length of the entire packet, excuding the
-	data_len field itself.
-
-opcode:
-	The BTSnoop opcode
-
-flags:
-	Special flags for the packet. Currently no flags are defined.
-
-hdr_len:
-	Length of the extended header.
-
-ext_hdr:
-	This is a sequence of header extension fields formatted as:
-
-	struct {
-		uint8_t type;
-		uint8_t value[length];
-	}
-
-	The length of the value is dependent on the type. Currently the
-	following types are defined:
-
-	Type                 Length    Meaning
-	----------------------------------------------------------------
-	1  Command drops     1 byte    Dropped HCI command packets
-	2  Event drops       1 byte    Dropped HCI event packets
-	3  ACL TX drops      1 byte    Dropped ACL TX packets
-	4  ACL RX drops      1 byte    Dropped ACL RX packets
-	5  SCO TX drops      1 byte    Dropped SCO TX packets
-	6  SCO RX drops      1 byte    Dropped SCO RX packets
-	7  Other drops       1 byte    Dropped other packets
-	8  32-bit timestamp  4 bytes   Timestamp in 1/10th ms
-
-	The drops fields indicate the number of packets that the
-	implementation had to drop (e.g. due to lack of buffers) since
-	the last reported drop count.
-
-	The fields of the extended header must be sorted by increasing
-	type. This is essential so that unknown types can be ignored and
-	the parser can jump to processing the payload.
-- 
2.52.0