From a779ec83c9266e552174a7490d5e5f40483699a0 Mon Sep 17 00:00:00 2001
From: Johan Hedberg <johan.hedberg@intel.com>
Date: Mon, 23 May 2016 10:09:57 +0300
Subject: [PATCH] doc: Add BTSnoop/Monitor protocol documentation

---
 Makefile.am     |  2 ++
 doc/btsnoop.txt | 59 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 61 insertions(+)
 create mode 100644 doc/btsnoop.txt

diff --git a/Makefile.am b/Makefile.am
index b34b633c6..701da6d4e 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -262,6 +262,8 @@ EXTRA_DIST += doc/obex-api.txt doc/obex-agent-api.txt
 EXTRA_DIST += doc/pics-opp.txt doc/pixit-opp.txt \
 		doc/pts-opp.txt
 
+EXTRA_DIST += doc/btsnoop.txt
+
 EXTRA_DIST += tools/magic.btsnoop
 
 AM_CFLAGS += @DBUS_CFLAGS@ @GLIB_CFLAGS@
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.