| 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 |
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 --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.