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:   Abhishek Pandit-Subedi <abhishekpandit@chromium.org>
To:     marcel@holtmann.org, luiz.dentz@gmail.com
Cc:     chromeos-bluetooth-upstreaming@chromium.org,
        linux-bluetooth@vger.kernel.org,
        Abhishek Pandit-Subedi <abhishekpandit@chromium.org>,
        Alain Michaud <alainm@chromium.org>,
        Miao-chen Chou <mcchou@chromium.org>
Subject: [Bluez PATCH] doc: Add Suspend and Resume events
Date:   Thu,  9 Jul 2020 14:10:02 -0700
Message-Id: <20200709140928.Bluez.1.I9181af521cf0fba8f4315c9b89975848d437d6dd@changeid>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Sender: linux-bluetooth-owner@vger.kernel.org
Precedence: bulk

Add Controller Suspend Event and Controller Resume Event to identify
suspend or resume of the Bluetooth stack has occurred.

Also update Device Disconnected Event to indicate a new disconnect
reason: "Connection terminated by local host for suspend"

Reviewed-by: Alain Michaud <alainm@chromium.org>
Reviewed-by: Miao-chen Chou <mcchou@chromium.org>
---

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

diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt
index ca0d38469..f79c0222c 100644
--- a/doc/mgmt-api.txt
+++ b/doc/mgmt-api.txt
@@ -3834,6 +3834,7 @@ Device Disconnected Event
 		2	Connection terminated by local host
 		3	Connection terminated by remote host
 		4	Connection terminated due to authentication failure
+		5	Connection terminated by local host for suspend
 
 	Note that the local/remote distinction just determines which side
 	terminated the low-level connection, regardless of the
@@ -4577,3 +4578,55 @@ Advertisement Monitor Removed Event
 
 	The event will only be sent to management sockets other than the
 	one through which the command was sent.
+
+
+Controller Suspend Event
+========================
+
+	Event code:		0x002d
+	Controller Index:	<controller_id>
+	Event Parameters:	Suspend_State (1 octet)
+
+	This event indicates that the controller is suspended for host suspend.
+
+	Possible values for the Suspend_State parameter:
+		0	Running (not disconnected)
+		1	Disconnected and not scanning
+		2	Page scanning and/or passive scanning.
+
+	The value 0 is used for the running state and may be sent if the
+	controller could not be configured to suspend properly.
+
+	This event will be sent to all management sockets.
+
+
+Controller Resume Event
+=======================
+
+	Event code:		0x002e
+	Controller Index:	<controller_id>
+	Event Parameters:	Address (6 octets)
+				Address_Type (1 octet)
+				Wake_Reason (1 octet)
+
+	This event indicates that the controller has resumed from suspend.
+
+	Possible values for the Wake_Reason parameter:
+		0	Unexpected Event
+		1	Resume from non-Bluetooth wake source
+		2	Connection Request (BR/EDR)
+		3	Connection Complete (BR/EDR)
+		4	LE Advertisement
+		5	LE Direct Advertisement
+		6	LE Extended Advertisement
+
+	We expect that only peer reconnections should wake us from the suspended
+	state. Any other events that cause a wakeup will be marked as Unexpected
+	Event.
+
+	If the Wake_Reason was any of the expected wake reasons (values 2-6),
+	the address of the peer device that caused the event will be shared in
+	Address and Address_Type. Otherwise, Address and Address_Type will both
+	be zero.
+
+	This event will be sent to all management sockets.
-- 
2.27.0.383.g050319c2ae-goog