From: Miao-chen Chou <mcchou@chromium.org>
To: Bluetooth Kernel Mailing List <linux-bluetooth@vger.kernel.org>
Cc: Michael Sun <michaelfsun@google.com>,
Yoni Shavit <yshavit@chromium.org>,
Alain Michaud <alainm@chromium.org>,
Luiz Augusto von Dentz <luiz.von.dentz@intel.com>,
Marcel Holtmann <marcel@holtmann.org>,
Miao-chen Chou <mcchou@chromium.org>
Subject: [BlueZ PATCH v8] doc: Describe the new Advertisement Monitor support
Date: Mon, 18 May 2020 20:37:31 -0700 [thread overview]
Message-ID: <20200518203627.BlueZ.v8.1.If9f6be992cbaeaa35423de29da6db28675b35fcc@changeid> (raw)
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 v8:
- Fix bit index of advertisement monitor feature and remove a tailing line.
Changes in v7:
- Update command/event opcodes after rebasing.
Changes in v6:
- Refine the description of commands.
- Add Monitor_Handle as the return parameter of Remove Advertisement
Monitor command.
Changes in v5:
- Add more fields in the return value of Read Advertisement Monitor
Features command.
- Refine the description of commands and events.
Changes in v4:
- In Read Advertisement Monitor Features command, rename
Adopted_Features to Enabled_Features.
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 | 146 +++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 146 insertions(+)
diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt
index b7c4db907..211f085fa 100644
--- a/doc/mgmt-api.txt
+++ b/doc/mgmt-api.txt
@@ -3218,6 +3218,124 @@ Set Experimental Feature Command
Invalid Index
+Read Advertisement Monitor Features Command
+===========================================
+
+ Command Code: 0x004b
+ Controller Index: <controller id>
+ Command Parameters:
+ Return Parameters: Supported_Features (4 Octets)
+ Enabled_Features (4 Octets)
+ Max_Num_Handles (2 Octets)
+ Max_Num_Patterns (1 Octet)
+ Num_Handles (2 Octets)
+ Handle1 (2 Octets)
+ Handle2 (2 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 Enabled_Features
+ lists the ones currently used by the kernel.
+
+ Supported_Features and Enabled_Features are bitmasks with currently
+ the following available bits:
+
+ 0 Advertisement content monitoring based on patterns with
+ logic OR.
+
+ Max_Num_Handles indicates the maximum number of supported
+ advertisement monitors. Note that the actual number of supported
+ ones might be less depending on the limitation of the controller.
+
+ Max_Num_Pattern indicates the maximum number of supported patterns
+ in an advertisement patterns monitor. Note that the actual number
+ of supported ones might be less depending on the limitation of the
+ controller.
+
+ Num_Handles indicates the number of added advertisement monitors,
+ and it is followed by a list of handles.
+
+ This command can be used when the controller is not powered.
+
+
+Add Advertisement Patterns Monitor Command
+=========================================
+
+ Command Code: 0x004c
+ Controller Index: <controller id>
+ Command Parameters: Pattern_Count (1 Octet)
+ Pattern1 {
+ AD_Type (1 Octet)
+ Offset (1 Octet)
+ Length (1 Octet)
+ Value (31 Octets)
+ }
+ Pattern2 { }
+ ...
+ Return Parameters: Monitor_Handle (2 Octets)
+
+ This command is used to add an advertisement monitor whose
+ filtering conditions are patterns. The kernel will trigger scanning
+ if there is at least one monitor added. 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 ignores 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 contains 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},
+ }
+
+ This command can be used when the controller is not powered and
+ all settings will be programmed once powered.
+
+ Possible errors: Failed
+ Busy
+ No Resources
+ Invalid Parameters
+
+
+Remove Advertisement Monitor Command
+====================================
+
+ Command Code: 0x004d
+ Controller Index: <controller id>
+ Command Parameters: Monitor_Handle (2 Octets)
+ Return Parameters: Monitor_Handle (2 Octets)
+
+ This command is used to remove advertisement monitor(s). The kernel
+ would remove the monitor(s) with Monitor_Handle and update the LE
+ scanning.
+
+ When the Monitor_Handle is set to zero, then all previously added
+ handles will be removed.
+
+ Removing a monitor while it is being added will be ignored.
+
+ This command can be used when the controller is not powered and
+ all settings will be programmed once powered.
+
+ Possible errors: Failed
+ Busy
+
+
Command Complete Event
======================
@@ -4118,3 +4236,31 @@ Experimental Feature Changed Event
one through which the change was triggered.
Refer to Set Experimental Feature command for the Flags parameter.
+
+
+Advertisement Monitor Added Event
+=================================
+
+ Event Code: 0x0028
+ Controller Index: <controller id>
+ Event Parameters: Monitor_Handle (2 Octets)
+
+ This event indicates that an advertisement monitor has been added
+ using the Add Advertisement Monitor command.
+
+ The event will only be sent to management sockets other than the
+ one through which the command was sent.
+
+
+Advertisement Monitor Removed Event
+===================================
+
+ Event Code: 0x0029
+ Controller Index: <controller id>
+ Event Parameters: Monitor_Handle (2 Octets)
+
+ This event indicates that an advertisement monitor has been removed
+ using the Remove Advertisement Monitor command.
+
+ The event will only be sent to management sockets other than the
+ one through which the command was sent.
--
2.26.2
next reply other threads:[~2020-05-19 3:37 UTC|newest]
Thread overview: 3+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-05-19 3:37 Miao-chen Chou [this message]
2020-05-27 21:26 ` [BlueZ PATCH v8] doc: Describe the new Advertisement Monitor support Miao-chen Chou
2020-06-10 17:56 ` Marcel Holtmann
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20200518203627.BlueZ.v8.1.If9f6be992cbaeaa35423de29da6db28675b35fcc@changeid \
--to=mcchou@chromium.org \
--cc=alainm@chromium.org \
--cc=linux-bluetooth@vger.kernel.org \
--cc=luiz.von.dentz@intel.com \
--cc=marcel@holtmann.org \
--cc=michaelfsun@google.com \
--cc=yshavit@chromium.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).