[BlueZ,v2] doc: Describe the new Advertisement Monitor support

Commit Message

Miao-chen Chou April 22, 2020, 1:02 a.m. UTC

This describes the following commands.
- Add Advertisement Patterns Monitor
- Remove 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 the
command of removing monitor(s), the Add command is tied to a specific type.
---

Changes in v2:
- Combine commands to remove one monitor and remove all monitors. The
refined command takes multiple handles and an extra field to indicate
whether to remove all monitors.

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

Comments

Marcel Holtmann April 22, 2020, 5:33 p.m. UTC | #1

Hi Miao-chen,

> This describes the following commands.
> - Add Advertisement Patterns Monitor
> - Remove 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 the
> command of removing monitor(s), the Add command is tied to a specific type.
> ---
> 
> Changes in v2:
> - Combine commands to remove one monitor and remove all monitors. The
> refined command takes multiple handles and an extra field to indicate
> whether to remove all monitors.
> 
> doc/mgmt-api.txt | 83 ++++++++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 83 insertions(+)
> 
> diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt
> index 39f23c456..d5d402361 100644
> --- a/doc/mgmt-api.txt
> +++ b/doc/mgmt-api.txt
> @@ -3138,6 +3138,89 @@ Read Security Information Command
> 				Invalid Index
> 
> 
> +Add Advertisement Patterns Monitor Command
> +=========================================

I wonder if we do Add Advertisement Monitor Pattern or Add Advertisement Monitor With Pattern.

> +
> +	Command Code:		0x0049
> +	Controller Index:	<controller id>
> +	Command Parameters:	Pattern_count (1 Octets)
> +				Pattern1 {
> +					AD_Data_Type (1 Octet)
> +					Offset (1 Octet)
> +					Length (1 Octet)
> +					Value (variable length)
> +				}
> +				Pattern2 { }
> +				...
> +	Return Parameters:	Monitor_Handle (8 Octets)

Why 8 Octets? How many do you expect? I would do 16-bit.

> +
> +	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. Note that if the there are more than one
> +	patterns, OR logic would applied among patterns during filtering. In
> +	other words, any advertisement matching at least one pattern in a given
> +	monitor would be considered as a match.
> +
> +	A pattern contain the following fields.
> +		AD_Data_Type	Advertising Data Type. The possible values are
> +				defined in Core Specification Supplement.
> +		Offset		The start index where pattern matching shall be
> +				performed with in the AD data.
> +		Length		The length of the pattern value in bytes.
> +		Value		The value of the pattern in bytes.
> +
> +	Here is an example of a pattern.
> +		{
> +			0x16, // Service Data - 16-bit UUID
> +			0x02, // Skip the UUID part.
> +			0x04,
> +			{0x11, 0x22, 0x33, 0x44},
> +		}
> +
> +	Possible errors:	Failed
> +				Busy
> +				Invalid Parameters
> +
> +
> +Remove Advertisement Monitors Command
> +=====================================

I would have a generic Remove Adveristement Monitor

> +
> +	Command Code:		0x004A
> +	Controller Index:	<controller id>
> +	Command Parameters:	Remove_All (1 Octet)

Skip the Remove_All. If you give Monitor_Count == 0, then it will remove all of them. This is how we have done the others.

> +				Monitor_Count (2 Octets)
> +				Monitor_Handle[i] (8 Octets)
> +	Return Parameters:	Removed_Monitor_Count (2 Octets)
> +				Removed_Monitor_Handle[i] (8 Octets)

Return values are not needed here.

> +
> +	This command is used to remove advertisement monitor(s). The kernel
> +	would remove the monitor(s) with Monitor_Index and update the LE
> +	scanning. If the controller supports Microsoft HCI extension and the
> +	monitor(s) has been offloaded, the kernel would cancel the offloading;
> +	otherwise the kernel takes no further actions other than removing the
> +	monitor(s) from the list.
> +
> +	Remove_All can be the following values.
> +		Value		Operation
> +		-------------------------
> +		0x00		Removes only the monitors with handles specified
> +				in Monitor_Handle[i], so there must be at least
> +				one handle.
> +		0x01		Removes all existing monitor(s), so
> +				Monitor_Count must be 0, and Monitor_Handle
> +				must be empty.
> +
> +	Possible errors:	Failed
> +				Busy
> +				Invalid Index
> +				Invalid Parameters
> +
> +
> Command Complete Event
> ======================

You are missing signals for Monitor Added and Monitor Removed.

And we are also missing a command for reading the basic supported features. Like we do for Advertising as well.

Regards

Marcel

Miao-chen Chou April 23, 2020, 1:10 a.m. UTC | #2

Hi Marcel,

On Wed, Apr 22, 2020 at 10:33 AM Marcel Holtmann <[e-mail]> wrote:
>
> Hi Miao-chen,
>
> > This describes the following commands.
> > - Add Advertisement Patterns Monitor
> > - Remove 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 the
> > command of removing monitor(s), the Add command is tied to a specific type.
> > ---
> >
> > Changes in v2:
> > - Combine commands to remove one monitor and remove all monitors. The
> > refined command takes multiple handles and an extra field to indicate
> > whether to remove all monitors.
> >
> > doc/mgmt-api.txt | 83 ++++++++++++++++++++++++++++++++++++++++++++++++
> > 1 file changed, 83 insertions(+)
> >
> > diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt
> > index 39f23c456..d5d402361 100644
> > --- a/doc/mgmt-api.txt
> > +++ b/doc/mgmt-api.txt
> > @@ -3138,6 +3138,89 @@ Read Security Information Command
> >                               Invalid Index
> >
> >
> > +Add Advertisement Patterns Monitor Command
> > +=========================================
>
> I wonder if we do Add Advertisement Monitor Pattern or Add Advertisement Monitor With Pattern.
>
> > +
> > +     Command Code:           0x0049
> > +     Controller Index:       <controller id>
> > +     Command Parameters:     Pattern_count (1 Octets)
> > +                             Pattern1 {
> > +                                     AD_Data_Type (1 Octet)
> > +                                     Offset (1 Octet)
> > +                                     Length (1 Octet)
> > +                                     Value (variable length)
> > +                             }
> > +                             Pattern2 { }
> > +                             ...
> > +     Return Parameters:      Monitor_Handle (8 Octets)
>
> Why 8 Octets? How many do you expect? I would do 16-bit.
My thought was that the number of monitor slots may not be fixed for
different extensions, so the idea was to have one-time handles which
will not be reused once a monitor was removed. If reusing the slots is
a preferable approach, given that Android and Microsoft extensions use
uint8 for indexing filters, we can use either uint16 or uint32 as the
index. I will put uint16 for now.
>
> > +
> > +     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. Note that if the there are more than one
> > +     patterns, OR logic would applied among patterns during filtering. In
> > +     other words, any advertisement matching at least one pattern in a given
> > +     monitor would be considered as a match.
> > +
> > +     A pattern contain the following fields.
> > +             AD_Data_Type    Advertising Data Type. The possible values are
> > +                             defined in Core Specification Supplement.
> > +             Offset          The start index where pattern matching shall be
> > +                             performed with in the AD data.
> > +             Length          The length of the pattern value in bytes.
> > +             Value           The value of the pattern in bytes.
> > +
> > +     Here is an example of a pattern.
> > +             {
> > +                     0x16, // Service Data - 16-bit UUID
> > +                     0x02, // Skip the UUID part.
> > +                     0x04,
> > +                     {0x11, 0x22, 0x33, 0x44},
> > +             }
> > +
> > +     Possible errors:        Failed
> > +                             Busy
> > +                             Invalid Parameters
> > +
> > +
> > +Remove Advertisement Monitors Command
> > +=====================================
>
> I would have a generic Remove Adveristement Monitor.  As requested, I will combine the remove and remove all operations by reserving 0 as a hint for removing all.
>
> > +
> > +     Command Code:           0x004A
> > +     Controller Index:       <controller id>
> > +     Command Parameters:     Remove_All (1 Octet)
>
> Skip the Remove_All. If you give Monitor_Count == 0, then it will remove all of them. This is how we have done the others.
>
> > +                             Monitor_Count (2 Octets)
> > +                             Monitor_Handle[i] (8 Octets)
> > +     Return Parameters:      Removed_Monitor_Count (2 Octets)
> > +                             Removed_Monitor_Handle[i] (8 Octets)
>
> Return values are not needed here.
>
> > +
> > +     This command is used to remove advertisement monitor(s). The kernel
> > +     would remove the monitor(s) with Monitor_Index and update the LE
> > +     scanning. If the controller supports Microsoft HCI extension and the
> > +     monitor(s) has been offloaded, the kernel would cancel the offloading;
> > +     otherwise the kernel takes no further actions other than removing the
> > +     monitor(s) from the list.
> > +
> > +     Remove_All can be the following values.
> > +             Value           Operation
> > +             -------------------------
> > +             0x00            Removes only the monitors with handles specified
> > +                             in Monitor_Handle[i], so there must be at least
> > +                             one handle.
> > +             0x01            Removes all existing monitor(s), so
> > +                             Monitor_Count must be 0, and Monitor_Handle
> > +                             must be empty.
> > +
> > +     Possible errors:        Failed
> > +                             Busy
> > +                             Invalid Index
> > +                             Invalid Parameters
> > +
> > +
> > Command Complete Event
> > ======================
>
> You are missing signals for Monitor Added and Monitor Removed.
Nice catch. I will add them in v3.
>
> And we are also missing a command for reading the basic supported features. Like we do for Advertising as well.
There was a comment made in the past discussion where we can introduce
a new setting(s) in the returned supported_settings of
MGMT_OP_READ_INFO command to indicate the features such as
MGMT_SETTING_HW_FILTERING . But given that there can be multiple
extensions, it may be preferable to have a separate command which
should be extendable.

Thanks,
Miao

Patch

diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt
index 39f23c456..d5d402361 100644
--- a/doc/mgmt-api.txt
+++ b/doc/mgmt-api.txt
@@ -3138,6 +3138,89 @@  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)
+					Offset (1 Octet)
+					Length (1 Octet)
+					Value (variable length)
+				}
+				Pattern2 { }
+				...
+	Return Parameters:	Monitor_Handle (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. Note that if the there are more than one
+	patterns, OR logic would applied among patterns during filtering. In
+	other words, any advertisement matching at least one pattern in a given
+	monitor would be considered as a match.
+
+	A pattern contain the following fields.
+		AD_Data_Type	Advertising Data Type. The possible values are
+				defined in Core Specification Supplement.
+		Offset		The start index where pattern matching shall be
+				performed with in the AD data.
+		Length		The length of the pattern value in bytes.
+		Value		The value of the pattern in bytes.
+
+	Here is an example of a pattern.
+		{
+			0x16, // Service Data - 16-bit UUID
+			0x02, // Skip the UUID part.
+			0x04,
+			{0x11, 0x22, 0x33, 0x44},
+		}
+
+	Possible errors:	Failed
+				Busy
+				Invalid Parameters
+
+
+Remove Advertisement Monitors Command
+=====================================
+
+	Command Code:		0x004A
+	Controller Index:	<controller id>
+	Command Parameters:	Remove_All (1 Octet)
+				Monitor_Count (2 Octets)
+				Monitor_Handle[i] (8 Octets)
+	Return Parameters:	Removed_Monitor_Count (2 Octets)
+				Removed_Monitor_Handle[i] (8 Octets)
+
+	This command is used to remove advertisement monitor(s). The kernel
+	would remove the monitor(s) with Monitor_Index and update the LE
+	scanning. If the controller supports Microsoft HCI extension and the
+	monitor(s) has been offloaded, the kernel would cancel the offloading;
+	otherwise the kernel takes no further actions other than removing the
+	monitor(s) from the list.
+
+	Remove_All can be the following values.
+		Value		Operation
+		-------------------------
+		0x00		Removes only the monitors with handles specified
+				in Monitor_Handle[i], so there must be at least
+				one handle.
+		0x01		Removes all existing monitor(s), so
+				Monitor_Count must be 0, and Monitor_Handle
+				must be empty.
+
+	Possible errors:	Failed
+				Busy
+				Invalid Index
+				Invalid Parameters
+
+
 Command Complete Event
 ======================