diff mbox series

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

Message ID 20200422180939.BlueZ.v2.1.If9f6be992cbaeaa35423de29da6db28675b35fcc@changeid (mailing list archive)
State Superseded
Headers show
Series [BlueZ,v2] doc: Describe the new Advertisement Monitor support | expand

Commit Message

Miao-chen Chou April 23, 2020, 1:09 a.m. UTC
This describes the following commands and event.
- Read Advertisement Monitor Features command
- Add Advertisement Patterns Monitor command
- Remove Advertisement Monitor command
- Advertisement Monitor Added event
- Advertisement Monitor Removed event
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 v3:
- Remove Advertisement Monitor can perform the removal of one monitor
or all monitors.
- Add Read Advertisement Monitor Features command.
- Add Advertisement Monitor Added event and dvertisement Monitor Removed
event.

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 | 118 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 118 insertions(+)

Comments

Miao-chen Chou April 23, 2020, 1:12 a.m. UTC | #1
Please ignore this patch, I should have update the version number.

On Wed, Apr 22, 2020 at 6:10 PM Miao-chen Chou <mcchou@chromium.org> wrote:
>
> This describes the following commands and event.
> - Read Advertisement Monitor Features command
> - Add Advertisement Patterns Monitor command
> - Remove Advertisement Monitor command
> - Advertisement Monitor Added event
> - Advertisement Monitor Removed event
> 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 v3:
> - Remove Advertisement Monitor can perform the removal of one monitor
> or all monitors.
> - Add Read Advertisement Monitor Features command.
> - Add Advertisement Monitor Added event and dvertisement Monitor Removed
> event.
>
> 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 | 118 +++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 118 insertions(+)
>
> diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt
> index 39f23c456..3cef3edbf 100644
> --- a/doc/mgmt-api.txt
> +++ b/doc/mgmt-api.txt
> @@ -3138,6 +3138,102 @@ Read Security Information Command
>                                 Invalid Index
>
>
> +Read Advertisement Monitor Features Command
> +===========================================
> +
> +       Command Code:           0x0049
> +       Controller Index:       <controller id>
> +       Command Parameters:
> +       Return Parameters:      Supported_Features (4 octets)
> +                               Adopted_Features (4 octets)
> +
> +       This command is used to read the advertisement monitor features supported
> +       by the controller and stack. Supported_Features lists all related
> +       features supported by the controller while Adopted_Features lists the
> +       ones currently adopted by the stack.
> +
> +       Supported_Features and Adopted_Features are bitmasks with currently the
> +       following available bits:
> +
> +               1       Advertisement content monitoring based on Microsoft HCI
> +                       extension.
> +
> +
> +Add Advertisement Patterns Monitor Command
> +=========================================
> +
> +       Command Code:           0x004A
> +       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 (4 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 advertisement filtering,
> +       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 Monitor Command
> +====================================
> +
> +       Command Code:           0x004B
> +       Controller Index:       <controller id>
> +       Command Parameters:     Monitor_Handle (4 Octets)
> +       Return Parameters:
> +
> +       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 advertisement filtering 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.
> +
> +       Monitor_Handle can be the following values.
> +               Value           Operation
> +               -------------------------
> +               0x00000000              Removes all existing monitor(s)
> +               0x00000001 or greater   Removes the monitor with that handle
> +
> +       Possible errors:        Failed
> +                               Busy
> +                               Invalid Index
> +
> +
>  Command Complete Event
>  ======================
>
> @@ -4020,3 +4116,25 @@ PHY Configuration Changed Event
>         one through which the change was triggered.
>
>         Refer Get PHY Configuration command for PHYs parameter.
> +
> +
> +Advertisement Monitor Added Event
> +=================================
> +
> +       Event Code:             0x0027
> +       Controller Index:       <controller id>
> +       Event Parameters:       Monitor_Handle (4 Octets)
> +
> +       This event indicates that an advertisement monitor has been added using
> +       the Add Advertisement Monitor command.
> +
> +
> +Advertisement Monitor Removed Event
> +===================================
> +
> +       Event Code:             0x0028
> +       Controller Index:       <controller id>
> +       Event Parameters:       Monitor_Handle (4 Octets)
> +
> +       This event indicates that an advertisement monitor has been removed
> +       using the Remove Advertisement Monitor command.
> --
> 2.24.1
>
diff mbox series

Patch

diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt
index 39f23c456..3cef3edbf 100644
--- a/doc/mgmt-api.txt
+++ b/doc/mgmt-api.txt
@@ -3138,6 +3138,102 @@  Read Security Information Command
 				Invalid Index
 
 
+Read Advertisement Monitor Features Command
+===========================================
+
+	Command Code:		0x0049
+	Controller Index:	<controller id>
+	Command Parameters:
+	Return Parameters:	Supported_Features (4 octets)
+				Adopted_Features (4 octets)
+
+	This command is used to read the advertisement monitor features supported
+	by the controller and stack. Supported_Features lists all related
+	features supported by the controller while Adopted_Features lists the
+	ones currently adopted by the stack.
+
+	Supported_Features and Adopted_Features are bitmasks with currently the
+	following available bits:
+
+		1	Advertisement content monitoring based on Microsoft HCI
+			extension.
+
+
+Add Advertisement Patterns Monitor Command
+=========================================
+
+	Command Code:		0x004A
+	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 (4 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 advertisement filtering,
+	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 Monitor Command
+====================================
+
+	Command Code:		0x004B
+	Controller Index:	<controller id>
+	Command Parameters:	Monitor_Handle (4 Octets)
+	Return Parameters:
+
+	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 advertisement filtering 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.
+
+	Monitor_Handle can be the following values.
+		Value		Operation
+		-------------------------
+		0x00000000		Removes all existing monitor(s)
+		0x00000001 or greater	Removes the monitor with that handle
+
+	Possible errors:	Failed
+				Busy
+				Invalid Index
+
+
 Command Complete Event
 ======================
 
@@ -4020,3 +4116,25 @@  PHY Configuration Changed Event
 	one through which the change was triggered.
 
 	Refer Get PHY Configuration command for PHYs parameter.
+
+
+Advertisement Monitor Added Event
+=================================
+
+	Event Code:		0x0027
+	Controller Index:	<controller id>
+	Event Parameters:	Monitor_Handle (4 Octets)
+
+	This event indicates that an advertisement monitor has been added using
+	the Add Advertisement Monitor command.
+
+
+Advertisement Monitor Removed Event
+===================================
+
+	Event Code:		0x0028
+	Controller Index:	<controller id>
+	Event Parameters:	Monitor_Handle (4 Octets)
+
+	This event indicates that an advertisement monitor has been removed
+	using the Remove Advertisement Monitor command.