Received-SPF: pass (google.com: domain of linux-bluetooth-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
From:   Miao-chen Chou <mcchou@chromium.org>
To:     Bluetooth Kernel Mailing List <linux-bluetooth@vger.kernel.org>
Cc:     Alain Michaud <alainm@chromium.org>,
        Luiz Augusto von Dentz <luiz.von.dentz@intel.com>,
        Marcel Holtmann <marcel@holtmann.org>,
        Michael Sun <michaelfsun@google.com>,
        Yoni Shavit <yshavit@chromium.org>,
        Miao-chen Chou <mcchou@chromium.org>
Subject: [BlueZ PATCH v1] doc: Describe the new Advertisement Monitor support
Date:   Fri, 17 Apr 2020 20:09:24 -0700
Message-Id: <20200417200903.BlueZ.v1.1.If9f6be992cbaeaa35423de29da6db28675b35fcc@changeid>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Sender: linux-bluetooth-owner@vger.kernel.org
Precedence: bulk

This describes the following commands.
- Add Advertisement Patterns Monitor
- Remove Advertisement Monitor
- Remove All Advertisement Monitors
Note that the content of a monitor can differ based on its type. For now we
introduce only pattern-based monitor, so you may find that unlike commands
for removing monitor(s), the Add command is tied to a specific type.

Signed-off-by: Miao-chen Chou <mcchou@chromium.org>
---

 doc/mgmt-api.txt | 68 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 68 insertions(+)

diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt
index 39f23c456..fcd281a35 100644
--- a/doc/mgmt-api.txt
+++ b/doc/mgmt-api.txt
@@ -3138,6 +3138,74 @@ Read Security Information Command
 				Invalid Index
 
 
+Add Advertisement Patterns Monitor Command
+=========================================
+
+	Command Code:		0x0049
+	Controller Index:	<controller id>
+	Command Parameters:	Pattern_count (1 Octets)
+				Pattern1 {
+					AD_Data_Type (1 Octet)
+					Index (1 Octet)
+					Length (1 Octet)
+					Value (variable length)
+				}
+				Pattern2 { }
+				...
+	Return Parameters:	Monitor_Index (8 Octets)
+
+	This command is used to add an advertisement monitor whose filtering
+	conditions are patterns. The kernel would track the number of registered
+	monitors to determine whether to perform LE scanning while there is
+	ongoing LE scanning for other intentions, such as auto-reconnection and
+	discovery session. If the controller supports Microsoft HCI extension,
+	the kernel would offload the content filtering to the controller in
+	order to reduce power consumption; otherwise the kernel ignore the
+	content of the monitor.
+
+	Possible errors:	Failed
+				Busy
+				Invalid Parameters
+
+
+Remove Advertisement Monitor Command
+====================================
+
+	Command Code:		0x004A
+	Controller Index:	<controller id>
+	Command Parameters:	Monitor_Index (8 Octets)
+	Return Parameters:	Monitor_Index (8 Octets)
+
+	This command is used to remove an advertisement monitor. The kernel
+	would remove the monitor with Monitor_Index and update the LE scanning.
+	If the controller supports Microsoft HCI extension and the monitor has
+	been offloaded, the kernel would cancel the offloading; otherwise the
+	kernel takes no further actions other than removing it from the list.
+
+	Possible errors:	Failed
+				Busy
+				Invalid Index
+
+
+Remove All Advertisement Monitors Command
+=========================================
+
+	Command Code:		0x004B
+	Controller Index:	<controller id>
+	Command Parameters:
+	Return Parameters:	Num_removed_Monitors (2 Octets)
+				Monitor_Index[i] (2 Octets)
+
+	This command is used to remove all advertisement monitors. The kernel
+	would remove all monitors and update the LE scanning if needed. If the
+	controller supports Microsoft HCI extension the monitors have been
+	offloaded, the kernel would cancel all offloadings; otherwise the kernel
+	takes no further actions other than removing all monitors from the list.
+
+	Possible errors:	Failed
+				Busy
+
+
 Command Complete Event
 ======================
 
-- 
2.24.1