doc: Add BTSnoop/Monitor protocol documentation

1 files changed, 59 insertions, 0 deletions

diff --git a/doc/btsnoop.txt b/doc/btsnoop.txt
new file mode 100644
index 000000000..ed56b5a1f
--- /dev/null
+++ b/doc/btsnoop.txt
@@ -0,0 +1,59 @@
+BTSnoop/Monitor protocol formats
+********************************
+
+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 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.