diff mbox series

[BlueZ,v4,1/8] doc: Introduce the quality report command and event

Message ID 20220215133636.2827039-1-josephsih@chromium.org
State New
Headers show
Series [BlueZ,v4,1/8] doc: Introduce the quality report command and event | expand

Commit Message

Joseph Hwang Feb. 15, 2022, 1:36 p.m. UTC
Add the MGMT quality report command and event in doc/mgmt-api.txt.

Signed-off-by: Joseph Hwang <josephsih@chromium.org>
---

Changes in v4:
- Use "Quality Report Event" without the prefix "Bluetooth" word.
- Combine both MGMT quality report command and event changes in a
  single patch.

Changes in v3:
- Swap AOSP Bluetooth Quality Report Event and Intel Telemetry Event.
- Add 5 new patches (5/9 - 9/9) to enable the quality report
  feature via MGMT_OP_SET_QUALITY_REPORT instead of through the
  experimental features.

Changes in v2:
- This is a new patch for adding the event in doc/mgmt-api.txt

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

Comments

bluez.test.bot@gmail.com Feb. 15, 2022, 3:58 p.m. UTC | #1
This is automated email and please do not reply to this email!

Dear submitter,

Thank you for submitting the patches to the linux bluetooth mailing list.
This is a CI test results with your patch series:
PW Link:https://patchwork.kernel.org/project/bluetooth/list/?series=614538

---Test result---

Test Summary:
CheckPatch                    PASS      12.28 seconds
GitLint                       FAIL      8.19 seconds
Prep - Setup ELL              PASS      46.49 seconds
Build - Prep                  PASS      0.74 seconds
Build - Configure             PASS      9.54 seconds
Build - Make                  PASS      1459.17 seconds
Make Check                    PASS      12.08 seconds
Make Check w/Valgrind         PASS      523.50 seconds
Make Distcheck                PASS      264.01 seconds
Build w/ext ELL - Configure   PASS      9.98 seconds
Build w/ext ELL - Make        PASS      1392.62 seconds
Incremental Build with patchesFAIL      4378.04 seconds

Details
##############################
Test: GitLint - FAIL
Desc: Run gitlint with rule in .gitlint
Output:
[BlueZ,v4,2/8] lib: Add structures and constants for quality report command and event
1: T1 Title exceeds max length (85>80): "[BlueZ,v4,2/8] lib: Add structures and constants for quality report command and event"


##############################
Test: Incremental Build with patches - FAIL
Desc: Incremental build per patch in the series
Output:
tools/mgmt-tester.c: In function ‘main’:
tools/mgmt-tester.c:12364:5: note: variable tracking size limit exceeded with ‘-fvar-tracking-assignments’, retrying without
12364 | int main(int argc, char *argv[])
      |     ^~~~
unit/test-avdtp.c: In function ‘main’:
unit/test-avdtp.c:766:5: note: variable tracking size limit exceeded with ‘-fvar-tracking-assignments’, retrying without
  766 | int main(int argc, char *argv[])
      |     ^~~~
unit/test-avrcp.c: In function ‘main’:
unit/test-avrcp.c:989:5: note: variable tracking size limit exceeded with ‘-fvar-tracking-assignments’, retrying without
  989 | int main(int argc, char *argv[])
      |     ^~~~
src/adapter.c:9744:6: error: no previous declaration for ‘is_quality_report_supported’ [-Werror=missing-declarations]
 9744 | bool is_quality_report_supported(struct btd_adapter *adapter)
      |      ^~~~~~~~~~~~~~~~~~~~~~~~~~~
cc1: all warnings being treated as errors
make[1]: *** [Makefile:10187: src/bluetoothd-adapter.o] Error 1
make: *** [Makefile:4308: all] Error 2




---
Regards,
Linux Bluetooth
Marcel Holtmann Feb. 17, 2022, 12:13 p.m. UTC | #2
Hi Joseph,

> Add the MGMT quality report command and event in doc/mgmt-api.txt.
> 
> Signed-off-by: Joseph Hwang <josephsih@chromium.org>
> ---
> 
> Changes in v4:
> - Use "Quality Report Event" without the prefix "Bluetooth" word.
> - Combine both MGMT quality report command and event changes in a
>  single patch.
> 
> Changes in v3:
> - Swap AOSP Bluetooth Quality Report Event and Intel Telemetry Event.
> - Add 5 new patches (5/9 - 9/9) to enable the quality report
>  feature via MGMT_OP_SET_QUALITY_REPORT instead of through the
>  experimental features.
> 
> Changes in v2:
> - This is a new patch for adding the event in doc/mgmt-api.txt
> 
> doc/mgmt-api.txt | 61 ++++++++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 61 insertions(+)
> 
> diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt
> index ebe56afa4..a494f5d7e 100644
> --- a/doc/mgmt-api.txt
> +++ b/doc/mgmt-api.txt
> @@ -332,6 +332,7 @@ Read Controller Information Command
> 		15	Static Address
> 		16	PHY Configuration
> 		17	Wideband Speech
> +		18	Quality Report
> 
> 	This command generates a Command Complete event on success or
> 	a Command Status event on failure.
> @@ -2924,6 +2925,7 @@ Read Extended Controller Information Command
> 		15	Static Address
> 		16	PHY Configuration
> 		17	Wideband Speech
> +		18	Quality Report
> 
> 	The EIR_Data field contains information about class of device,
> 	local name and other values. Not all of them might be present. For
> @@ -3858,6 +3860,46 @@ Add Advertisement Patterns Monitor With RSSI Threshold Command
> 				Invalid Parameters
> 
> 
> +Set Quality Report Command
> +==========================
> +
> +	Command Code:		0x0057
> +	Controller Index:	<controller id>
> +	Command Parameters:	Action (1 Octet)

I remember mentioning that we should use Quality_Report instead of Action.

> +	Return Parameters:	Current_Settings (4 Octets)
> +
> +	This command is used to enable and disable the controller's quality
> +	report feature. The allowed values for the Action command parameter
> +	are 0x00 and 0x01. All other values will return Invalid Parameters.
> +
> +	The value 0x00 disables the Quality Report, and the value 0x01
> +	enables the Quality Report feature.
> +
> +	This command is only available for the controllers that support
> +	either AOSP Bluetooth quality report or Intel telemetry event.

The details below are interesting, but don’t have to be in this document. It is supported if the Supported_Settings indicate support for it.

> +	For a controller supporting the AOSP specification, it should call
> +	hci_set_aosp_capable() in its driver. The controller should also
> +	return version_supported v0.98 or higher in its Vendor-specific
> +	capabilities responding to the LE_Get_Vendor_Capabilities_Command.
> +	On the other hand, for a controller supporting Intel specification,
> +	it should set up the set_quality_report callback properly. The driver
> +	is responsible of setting up the quality report capability as
> +	described above; otherwise, a Not Supported status will be returned.
> +
> +	This command requires to use a valid controller index. Otherwise,
> +	an Invalid Index status will be returned.
> +
> +	The command is sent to the controller to enable/disable the quality
> +	report feature, and generates a Command Complete event on success.
> +	If the controller failed to execute the action, a Failed status will
> +	be returned.

Can this be used when powered off, is it remembered over power off/on cycles etc.

> +
> +	Possible errors:	Failed
> +				Invalid Index
> +				Invalid Parameters
> +				Not Supported
> +
> +
> Command Complete Event
> ======================
> 
> @@ -4978,3 +5020,22 @@ Advertisement Monitor Device Lost Event
> 		2	LE Random
> 
> 	This event will be sent to all management sockets.
> +
> +
> +Quality Report Event
> +====================
> +
> +	Event code:		0x0031
> +	Controller Index:	<controller_id>
> +	Event Parameters:	Quality_Spec (1 Octet)
> +				Report_Len (2 Octets)
> +				Report (0-65535 Octets)
> +
> +	This event carries the Bluetooth quality report sent by the
> +	controller.
> +
> +	Possible values for the Quality_Spec parameter:
> +		0	AOSP Bluetooth Quality Report Event
> +		1	Intel Telemetry Event
> +
> +	This event will be sent to all management sockets.

Regards

Marcel
Joseph Hwang March 5, 2022, 7:57 a.m. UTC | #3
Hi Marcel, thank you for reviewing the patches! Please read my replies
in the lines below. Thanks!

On Thu, Feb 17, 2022 at 8:13 PM Marcel Holtmann <marcel@holtmann.org> wrote:
>
> Hi Joseph,
>
> > Add the MGMT quality report command and event in doc/mgmt-api.txt.
> >
> > Signed-off-by: Joseph Hwang <josephsih@chromium.org>
> > ---
> >
> > Changes in v4:
> > - Use "Quality Report Event" without the prefix "Bluetooth" word.
> > - Combine both MGMT quality report command and event changes in a
> >  single patch.
> >
> > Changes in v3:
> > - Swap AOSP Bluetooth Quality Report Event and Intel Telemetry Event.
> > - Add 5 new patches (5/9 - 9/9) to enable the quality report
> >  feature via MGMT_OP_SET_QUALITY_REPORT instead of through the
> >  experimental features.
> >
> > Changes in v2:
> > - This is a new patch for adding the event in doc/mgmt-api.txt
> >
> > doc/mgmt-api.txt | 61 ++++++++++++++++++++++++++++++++++++++++++++++++
> > 1 file changed, 61 insertions(+)
> >
> > diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt
> > index ebe56afa4..a494f5d7e 100644
> > --- a/doc/mgmt-api.txt
> > +++ b/doc/mgmt-api.txt
> > @@ -332,6 +332,7 @@ Read Controller Information Command
> >               15      Static Address
> >               16      PHY Configuration
> >               17      Wideband Speech
> > +             18      Quality Report
> >
> >       This command generates a Command Complete event on success or
> >       a Command Status event on failure.
> > @@ -2924,6 +2925,7 @@ Read Extended Controller Information Command
> >               15      Static Address
> >               16      PHY Configuration
> >               17      Wideband Speech
> > +             18      Quality Report
> >
> >       The EIR_Data field contains information about class of device,
> >       local name and other values. Not all of them might be present. For
> > @@ -3858,6 +3860,46 @@ Add Advertisement Patterns Monitor With RSSI Threshold Command
> >                               Invalid Parameters
> >
> >
> > +Set Quality Report Command
> > +==========================
> > +
> > +     Command Code:           0x0057
> > +     Controller Index:       <controller id>
> > +     Command Parameters:     Action (1 Octet)
>
> I remember mentioning that we should use Quality_Report instead of Action.
>
> > +     Return Parameters:      Current_Settings (4 Octets)
> > +
> > +     This command is used to enable and disable the controller's quality
> > +     report feature. The allowed values for the Action command parameter
> > +     are 0x00 and 0x01. All other values will return Invalid Parameters.
> > +
> > +     The value 0x00 disables the Quality Report, and the value 0x01
> > +     enables the Quality Report feature.
> > +
> > +     This command is only available for the controllers that support
> > +     either AOSP Bluetooth quality report or Intel telemetry event.
>
> The details below are interesting, but don’t have to be in this document. It is supported if the Supported_Settings indicate support for it.
>
> > +     For a controller supporting the AOSP specification, it should call
> > +     hci_set_aosp_capable() in its driver. The controller should also
> > +     return version_supported v0.98 or higher in its Vendor-specific
> > +     capabilities responding to the LE_Get_Vendor_Capabilities_Command.
> > +     On the other hand, for a controller supporting Intel specification,
> > +     it should set up the set_quality_report callback properly. The driver
> > +     is responsible of setting up the quality report capability as
> > +     described above; otherwise, a Not Supported status will be returned.
> > +
> > +     This command requires to use a valid controller index. Otherwise,
> > +     an Invalid Index status will be returned.
> > +
> > +     The command is sent to the controller to enable/disable the quality
> > +     report feature, and generates a Command Complete event on success.
> > +     If the controller failed to execute the action, a Failed status will
> > +     be returned.
>
> Can this be used when powered off, is it remembered over power off/on cycles etc.

It is not remembered by the Intel controller over power cycles. I will
test the other AOSP vendors, and plan to address this issue in
separate patches in which I will describe the behavior explicitly.
Thanks.

>
> > +
> > +     Possible errors:        Failed
> > +                             Invalid Index
> > +                             Invalid Parameters
> > +                             Not Supported
> > +
> > +
> > Command Complete Event
> > ======================
> >
> > @@ -4978,3 +5020,22 @@ Advertisement Monitor Device Lost Event
> >               2       LE Random
> >
> >       This event will be sent to all management sockets.
> > +
> > +
> > +Quality Report Event
> > +====================
> > +
> > +     Event code:             0x0031
> > +     Controller Index:       <controller_id>
> > +     Event Parameters:       Quality_Spec (1 Octet)
> > +                             Report_Len (2 Octets)
> > +                             Report (0-65535 Octets)
> > +
> > +     This event carries the Bluetooth quality report sent by the
> > +     controller.
> > +
> > +     Possible values for the Quality_Spec parameter:
> > +             0       AOSP Bluetooth Quality Report Event
> > +             1       Intel Telemetry Event
> > +
> > +     This event will be sent to all management sockets.
>
> Regards
>
> Marcel
>
Marcel Holtmann March 5, 2022, 9:53 p.m. UTC | #4
Hi Joseph,

>>> Add the MGMT quality report command and event in doc/mgmt-api.txt.
>>> 
>>> Signed-off-by: Joseph Hwang <josephsih@chromium.org>
>>> ---
>>> 
>>> Changes in v4:
>>> - Use "Quality Report Event" without the prefix "Bluetooth" word.
>>> - Combine both MGMT quality report command and event changes in a
>>> single patch.
>>> 
>>> Changes in v3:
>>> - Swap AOSP Bluetooth Quality Report Event and Intel Telemetry Event.
>>> - Add 5 new patches (5/9 - 9/9) to enable the quality report
>>> feature via MGMT_OP_SET_QUALITY_REPORT instead of through the
>>> experimental features.
>>> 
>>> Changes in v2:
>>> - This is a new patch for adding the event in doc/mgmt-api.txt
>>> 
>>> doc/mgmt-api.txt | 61 ++++++++++++++++++++++++++++++++++++++++++++++++
>>> 1 file changed, 61 insertions(+)
>>> 
>>> diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt
>>> index ebe56afa4..a494f5d7e 100644
>>> --- a/doc/mgmt-api.txt
>>> +++ b/doc/mgmt-api.txt
>>> @@ -332,6 +332,7 @@ Read Controller Information Command
>>>              15      Static Address
>>>              16      PHY Configuration
>>>              17      Wideband Speech
>>> +             18      Quality Report
>>> 
>>>      This command generates a Command Complete event on success or
>>>      a Command Status event on failure.
>>> @@ -2924,6 +2925,7 @@ Read Extended Controller Information Command
>>>              15      Static Address
>>>              16      PHY Configuration
>>>              17      Wideband Speech
>>> +             18      Quality Report
>>> 
>>>      The EIR_Data field contains information about class of device,
>>>      local name and other values. Not all of them might be present. For
>>> @@ -3858,6 +3860,46 @@ Add Advertisement Patterns Monitor With RSSI Threshold Command
>>>                              Invalid Parameters
>>> 
>>> 
>>> +Set Quality Report Command
>>> +==========================
>>> +
>>> +     Command Code:           0x0057
>>> +     Controller Index:       <controller id>
>>> +     Command Parameters:     Action (1 Octet)
>> 
>> I remember mentioning that we should use Quality_Report instead of Action.
>> 
>>> +     Return Parameters:      Current_Settings (4 Octets)
>>> +
>>> +     This command is used to enable and disable the controller's quality
>>> +     report feature. The allowed values for the Action command parameter
>>> +     are 0x00 and 0x01. All other values will return Invalid Parameters.
>>> +
>>> +     The value 0x00 disables the Quality Report, and the value 0x01
>>> +     enables the Quality Report feature.
>>> +
>>> +     This command is only available for the controllers that support
>>> +     either AOSP Bluetooth quality report or Intel telemetry event.
>> 
>> The details below are interesting, but don’t have to be in this document. It is supported if the Supported_Settings indicate support for it.
>> 
>>> +     For a controller supporting the AOSP specification, it should call
>>> +     hci_set_aosp_capable() in its driver. The controller should also
>>> +     return version_supported v0.98 or higher in its Vendor-specific
>>> +     capabilities responding to the LE_Get_Vendor_Capabilities_Command.
>>> +     On the other hand, for a controller supporting Intel specification,
>>> +     it should set up the set_quality_report callback properly. The driver
>>> +     is responsible of setting up the quality report capability as
>>> +     described above; otherwise, a Not Supported status will be returned.
>>> +
>>> +     This command requires to use a valid controller index. Otherwise,
>>> +     an Invalid Index status will be returned.
>>> +
>>> +     The command is sent to the controller to enable/disable the quality
>>> +     report feature, and generates a Command Complete event on success.
>>> +     If the controller failed to execute the action, a Failed status will
>>> +     be returned.
>> 
>> Can this be used when powered off, is it remembered over power off/on cycles etc.
> 
> It is not remembered by the Intel controller over power cycles. I will
> test the other AOSP vendors, and plan to address this issue in
> separate patches in which I will describe the behavior explicitly.
> Thanks.

I think this means that on every power on we have to reprogram it if it was enabled before. That is how we handle other settings. They survive power cycles. And since we have a Current_Settings flags for this, I would expect it to behave exactly the same.

Regards

Marcel
Joseph Hwang March 6, 2022, 4:23 a.m. UTC | #5
Hi Marcel:
  What I plan to do about adapter power cycle for quality report:

  Step 1: At power off, do not clear the flag of HCI_QUALITY_REPORT in
hci_dev_clear_volatile_flags(). Will use HCI_QUALITY_REPORT to track
if the quality report is enabled before power off. Will also disable
the quality report explicitly in hci_sync.c:hci_dev_open_sync() just
before aosp_do_close()  so that different vendor chips will have
quality off at power off.

  Step 2: In hci_sync.c:hci_dev_open_sync(), re-enable quality report
explicitly just after aosp_do_open() if HCI_QUALITY_REPORT is true so
that all vendor chips have quality back on at power on.

  If the quality report is not enabled before power cycle,
HCI_QUALITY_REPORT will always stay false. Nothing mentioned above
will be executed in this case.

  One thing is worth noting here. The HCI_QUALITY_REPORT represents
the host setting instead of the controller state. During power off,
the HCI_QUALITY_REPORT host setting remains true while the controller
state about quality report is turned off. This behavior is similar to
"wide-band-speech" whose setting remains true during power off.

  Does this sound good to you? If yes, I will append a new patch to
the next Series-version. Thanks!

On Sun, Mar 6, 2022 at 5:53 AM Marcel Holtmann <marcel@holtmann.org> wrote:
>
> Hi Joseph,
>
> >>> Add the MGMT quality report command and event in doc/mgmt-api.txt.
> >>>
> >>> Signed-off-by: Joseph Hwang <josephsih@chromium.org>
> >>> ---
> >>>
> >>> Changes in v4:
> >>> - Use "Quality Report Event" without the prefix "Bluetooth" word.
> >>> - Combine both MGMT quality report command and event changes in a
> >>> single patch.
> >>>
> >>> Changes in v3:
> >>> - Swap AOSP Bluetooth Quality Report Event and Intel Telemetry Event.
> >>> - Add 5 new patches (5/9 - 9/9) to enable the quality report
> >>> feature via MGMT_OP_SET_QUALITY_REPORT instead of through the
> >>> experimental features.
> >>>
> >>> Changes in v2:
> >>> - This is a new patch for adding the event in doc/mgmt-api.txt
> >>>
> >>> doc/mgmt-api.txt | 61 ++++++++++++++++++++++++++++++++++++++++++++++++
> >>> 1 file changed, 61 insertions(+)
> >>>
> >>> diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt
> >>> index ebe56afa4..a494f5d7e 100644
> >>> --- a/doc/mgmt-api.txt
> >>> +++ b/doc/mgmt-api.txt
> >>> @@ -332,6 +332,7 @@ Read Controller Information Command
> >>>              15      Static Address
> >>>              16      PHY Configuration
> >>>              17      Wideband Speech
> >>> +             18      Quality Report
> >>>
> >>>      This command generates a Command Complete event on success or
> >>>      a Command Status event on failure.
> >>> @@ -2924,6 +2925,7 @@ Read Extended Controller Information Command
> >>>              15      Static Address
> >>>              16      PHY Configuration
> >>>              17      Wideband Speech
> >>> +             18      Quality Report
> >>>
> >>>      The EIR_Data field contains information about class of device,
> >>>      local name and other values. Not all of them might be present. For
> >>> @@ -3858,6 +3860,46 @@ Add Advertisement Patterns Monitor With RSSI Threshold Command
> >>>                              Invalid Parameters
> >>>
> >>>
> >>> +Set Quality Report Command
> >>> +==========================
> >>> +
> >>> +     Command Code:           0x0057
> >>> +     Controller Index:       <controller id>
> >>> +     Command Parameters:     Action (1 Octet)
> >>
> >> I remember mentioning that we should use Quality_Report instead of Action.
> >>
> >>> +     Return Parameters:      Current_Settings (4 Octets)
> >>> +
> >>> +     This command is used to enable and disable the controller's quality
> >>> +     report feature. The allowed values for the Action command parameter
> >>> +     are 0x00 and 0x01. All other values will return Invalid Parameters.
> >>> +
> >>> +     The value 0x00 disables the Quality Report, and the value 0x01
> >>> +     enables the Quality Report feature.
> >>> +
> >>> +     This command is only available for the controllers that support
> >>> +     either AOSP Bluetooth quality report or Intel telemetry event.
> >>
> >> The details below are interesting, but don’t have to be in this document. It is supported if the Supported_Settings indicate support for it.
> >>
> >>> +     For a controller supporting the AOSP specification, it should call
> >>> +     hci_set_aosp_capable() in its driver. The controller should also
> >>> +     return version_supported v0.98 or higher in its Vendor-specific
> >>> +     capabilities responding to the LE_Get_Vendor_Capabilities_Command.
> >>> +     On the other hand, for a controller supporting Intel specification,
> >>> +     it should set up the set_quality_report callback properly. The driver
> >>> +     is responsible of setting up the quality report capability as
> >>> +     described above; otherwise, a Not Supported status will be returned.
> >>> +
> >>> +     This command requires to use a valid controller index. Otherwise,
> >>> +     an Invalid Index status will be returned.
> >>> +
> >>> +     The command is sent to the controller to enable/disable the quality
> >>> +     report feature, and generates a Command Complete event on success.
> >>> +     If the controller failed to execute the action, a Failed status will
> >>> +     be returned.
> >>
> >> Can this be used when powered off, is it remembered over power off/on cycles etc.
> >
> > It is not remembered by the Intel controller over power cycles. I will
> > test the other AOSP vendors, and plan to address this issue in
> > separate patches in which I will describe the behavior explicitly.
> > Thanks.
>
> I think this means that on every power on we have to reprogram it if it was enabled before. That is how we handle other settings. They survive power cycles. And since we have a Current_Settings flags for this, I would expect it to behave exactly the same.
>
> Regards
>
> Marcel
>
Marcel Holtmann March 6, 2022, 8:49 a.m. UTC | #6
Hi Joseph,

>  What I plan to do about adapter power cycle for quality report:
> 
>  Step 1: At power off, do not clear the flag of HCI_QUALITY_REPORT in
> hci_dev_clear_volatile_flags(). Will use HCI_QUALITY_REPORT to track
> if the quality report is enabled before power off. Will also disable
> the quality report explicitly in hci_sync.c:hci_dev_open_sync() just
> before aosp_do_close()  so that different vendor chips will have
> quality off at power off.
> 
>  Step 2: In hci_sync.c:hci_dev_open_sync(), re-enable quality report
> explicitly just after aosp_do_open() if HCI_QUALITY_REPORT is true so
> that all vendor chips have quality back on at power on.
> 
>  If the quality report is not enabled before power cycle,
> HCI_QUALITY_REPORT will always stay false. Nothing mentioned above
> will be executed in this case.
> 
>  One thing is worth noting here. The HCI_QUALITY_REPORT represents
> the host setting instead of the controller state. During power off,
> the HCI_QUALITY_REPORT host setting remains true while the controller
> state about quality report is turned off. This behavior is similar to
> "wide-band-speech" whose setting remains true during power off.
> 
>  Does this sound good to you? If yes, I will append a new patch to
> the next Series-version. Thanks!

yes, that sounds good. Please provide the mgmt addition as first patches.

Regards

Marcel
diff mbox series

Patch

diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt
index ebe56afa4..a494f5d7e 100644
--- a/doc/mgmt-api.txt
+++ b/doc/mgmt-api.txt
@@ -332,6 +332,7 @@  Read Controller Information Command
 		15	Static Address
 		16	PHY Configuration
 		17	Wideband Speech
+		18	Quality Report
 
 	This command generates a Command Complete event on success or
 	a Command Status event on failure.
@@ -2924,6 +2925,7 @@  Read Extended Controller Information Command
 		15	Static Address
 		16	PHY Configuration
 		17	Wideband Speech
+		18	Quality Report
 
 	The EIR_Data field contains information about class of device,
 	local name and other values. Not all of them might be present. For
@@ -3858,6 +3860,46 @@  Add Advertisement Patterns Monitor With RSSI Threshold Command
 				Invalid Parameters
 
 
+Set Quality Report Command
+==========================
+
+	Command Code:		0x0057
+	Controller Index:	<controller id>
+	Command Parameters:	Action (1 Octet)
+	Return Parameters:	Current_Settings (4 Octets)
+
+	This command is used to enable and disable the controller's quality
+	report feature. The allowed values for the Action command parameter
+	are 0x00 and 0x01. All other values will return Invalid Parameters.
+
+	The value 0x00 disables the Quality Report, and the value 0x01
+	enables the Quality Report feature.
+
+	This command is only available for the controllers that support
+	either AOSP Bluetooth quality report or Intel telemetry event.
+	For a controller supporting the AOSP specification, it should call
+	hci_set_aosp_capable() in its driver. The controller should also
+	return version_supported v0.98 or higher in its Vendor-specific
+	capabilities responding to the LE_Get_Vendor_Capabilities_Command.
+	On the other hand, for a controller supporting Intel specification,
+	it should set up the set_quality_report callback properly. The driver
+	is responsible of setting up the quality report capability as
+	described above; otherwise, a Not Supported status will be returned.
+
+	This command requires to use a valid controller index. Otherwise,
+	an Invalid Index status will be returned.
+
+	The command is sent to the controller to enable/disable the quality
+	report feature, and generates a Command Complete event on success.
+	If the controller failed to execute the action, a Failed status will
+	be returned.
+
+	Possible errors:	Failed
+				Invalid Index
+				Invalid Parameters
+				Not Supported
+
+
 Command Complete Event
 ======================
 
@@ -4978,3 +5020,22 @@  Advertisement Monitor Device Lost Event
 		2	LE Random
 
 	This event will be sent to all management sockets.
+
+
+Quality Report Event
+====================
+
+	Event code:		0x0031
+	Controller Index:	<controller_id>
+	Event Parameters:	Quality_Spec (1 Octet)
+				Report_Len (2 Octets)
+				Report (0-65535 Octets)
+
+	This event carries the Bluetooth quality report sent by the
+	controller.
+
+	Possible values for the Quality_Spec parameter:
+		0	AOSP Bluetooth Quality Report Event
+		1	Intel Telemetry Event
+
+	This event will be sent to all management sockets.