From: Miao-chen Chou <mcchou@chromium.org>
To: Bluetooth Kernel Mailing List <linux-bluetooth@vger.kernel.org>
Cc: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>,
Marcel Holtmann <marcel@holtmann.org>,
Alain Michaud <alainm@chromium.org>,
Michael Sun <michaelfsun@google.com>,
Yoni Shavit <yshavit@chromium.org>
Subject: Re: [BlueZ PATCH v6] doc: Describe the new Advertisement Monitor support
Date: Mon, 18 May 2020 14:17:43 -0700 [thread overview]
Message-ID: <CABmPvSFUJLfjZj139p_XaSobMYb49GUTBB1xDzGhiu5mQ-1knA@mail.gmail.com> (raw)
In-Reply-To: <20200507145354.BlueZ.v6.1.If9f6be992cbaeaa35423de29da6db28675b35fcc@changeid>
Hi Marcel and Luiz,
Can you help with giving more comments if any?
Thanks,
Miao
On Thu, May 7, 2020 at 2:54 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 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 | 147 +++++++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 147 insertions(+)
>
> diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt
> index 39f23c456..3290cc76f 100644
> --- a/doc/mgmt-api.txt
> +++ b/doc/mgmt-api.txt
> @@ -3138,6 +3138,125 @@ 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)
> + 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:
> +
> + 1 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: 0x004A
> + 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: 0x004B
> + 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
> + Invalid Index
> +
> +
> Command Complete Event
> ======================
>
> @@ -4020,3 +4139,31 @@ 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 (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: 0x0028
> + 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.24.1
>
prev parent reply other threads:[~2020-05-18 21:17 UTC|newest]
Thread overview: 2+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-05-07 21:54 [BlueZ PATCH v6] doc: Describe the new Advertisement Monitor support Miao-chen Chou
2020-05-18 21:17 ` Miao-chen Chou [this message]
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=CABmPvSFUJLfjZj139p_XaSobMYb49GUTBB1xDzGhiu5mQ-1knA@mail.gmail.com \
--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).