doc: Describe the new Advertisement Monitor support

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.

Signed-off-by: Anuj Jain <anuj01.jain@samsung.com>
Signed-off-by: Ayush Garg <ayush.garg@samsung.com>

diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt
index 547eb74..9580849 100755 (executable)
--- a/doc/mgmt-api.txt
+++ b/doc/mgmt-api.txt
@@ -104,8 +104,10 @@ Version 1.18 introduces Read Default System Configuration command, Set
 Default System Configuration command, Default System Configuration Changed
 event, Read Default Runtime Configuration command, Set Default Runtime
 Configuration command, Default Runtime Configuration Changed event, Get
-Device Flags command, Set Device Flags command and Device Flags Changed
-event.
+Device Flags command, Set Device Flags command, Device Flags Changed event,
+Read Advertisement Monitor Features command, Add Advertisement Patterns
+Monitor command, Remove Advertisement Monitor command, Advertisement Monitor
+Added event and Advertisement Monitor Removed event.
 
 
 Example
@@ -3515,6 +3517,124 @@ Set Device Flags Command
                                Invalid Index
 
 
+Read Advertisement Monitor Features Command
+===========================================
+
+       Command Code:           0x0051
+       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:           0x0052
+       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:           0x0053
+       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
 ======================
 
@@ -4490,3 +4610,31 @@ Device Flags Changed Event
 
        In case this event is triggered by Add Device then it is sent to
        all management sockets.
+
+
+Advertisement Monitor Added Event
+=================================
+
+       Event Code:             0x002b
+       Controller Index:       <controller id>
+       Event Parameters:       Monitor_Handle (2 Octets)
+
+       This event indicates that an advertisement monitor has been added
+       using the Add Advertisement Patterns 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:             0x002c
+       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.